[osis-editors] Review of 2.0.1 User's Manual - Draft
Patrick Durusau
osis-editors@bibletechnologieswg.org
Fri, 16 Jan 2004 09:32:37 -0500
Jim,
Finally back on the OSIS Users Manual! Apologies again for the delayed
response.
I am not going to respond to your comments and corrections other than to
say Wow! Thought I typed better than that! ;-)
Will be busy correcting the text for a while so responses to your other
posts will be forthcoming, hopefully later today. I have some correcting
to do.
Hope you are having a great day!
Patrick
Jim Schaad wrote:
> Gentlemen, you wanted comments and corrections -- here they are.
>
> I downloaded and read the user's manual on Jan 03.
>
> 1. Title of section 14. refererence -> reference
>
> 2. Section 5: Are you only allowing UTF-8 encoding? This is implied
> from the text that the first line must be copied exactly. This is not a
> requirement (although is the ususal case) for XML. You could, for
> example, use UTF-16.
>
> 3. Section 5: There is a statement that every osisText needs to specify
> the reference scheme, but none of the schemes listed are in the osisText
> statement. Nor is the attribute needed to do this referencing stated.
>
> 4. Section 5: discussion is missing on osisRefWork attribute
>
> 5. Section 5: discussion is missing on lang attribute (reference to
> later section would be sufficent).
>
> 7. Section 7.1 - The date format is inconsistant between here and
> section 7.5. one uses hh:mm:ss and the other uses hh.mm.ss. Also in
> section 7.3.4.
>
> 8. Section 7.1 - Example should be using the resp attribute as
> document.
>
> 9. Section 7.2 - change "osisIDRef" to "osisIDWork" in the second
> paragraph.
>
> 10. Section 7.2 - "can then be referred to from osisIDs or osisRefs" I
> would have though that all osisIDs must be fore the current (containing)
> work. osisRefs can refer to other works but not osisIDs?
> -------EXPLAIN------
>
> 11. Section 7.2 - Text describing short names appears to allow for
> astricks. Correct discription would be "Short names consist of letters,
> numbers and the underscore character."
>
> 12. Section 7.3 - contributor and creator order is swapped from schema
>
> 13. Section 7.3 - type is out of order from schema
>
> 14. Section 7.3 - language and identifier order is swapped from schema
>
> 15. Section 7.3 - should have a list of the order of the elements.
> This should not need to be implied from the examples - where the
> examples do not list every element. Either that or the sentence "must
> be encoded in the order shown here." Should be removed.
>
> 16. Section 7.* - Are these suppose to be in the same order as the
> schema? It's not even close.
>
> 17. Section 7.3.2 - Appendix D is titled Contributor roles, but is
> referenced from the creator not the contributor section. I suggest
> referencing from both locations and changing to "Creator and
> Contributor Roles"
>
> 18. Section 7.3.4 - How do I specify a date a cira? If one is looking
> at say, Mark, one might say original is dated cira 0070. --- Response:
> 7.5 ~0070
>
> 19. Seciton 7.3.6 - Given the number of different ways that I can
> specify the language to be english, do we need to have some type of
> equivancy tables? Or is there an order of preference for using the
> different types?
>
> 20. Seciton 7.3.7 - If there is an OSIS type, then the legal types need
> to be listed here. If there is not an OSIS type, then remove it from
> the example.
>
> 21. Section 7.3.8 - Need to define the content of type="OSIS" for
> identifier so we know what to expect here.
>
> 22. Section 7.3.10 - If description is a simple content, then it is
> difficult to put complex data like tables of contents into it and make
> it usable.
>
> 23. Section 7.3.14.2 - I believe this should be up a level in the
> heirarchy.
>
> 24. Section 7.3.14.3 - I believe this is a duplicate of section 7.3.7
>
> 25. Section 7.3.15.1 - States scope elements must have an osisRef
> attribute, but this is missing in the example in section 4.
>
> 26. Section 7.3.15.1 - If the reference is in canonical order, are text
> eleemnts within the actual text required to be in canonical order as
> well?
>
> 27. Section 7.5: States there are 3 standard date formats, but only two
> are listed.
>
> 28. Section 7.5: Please remove requirement that years always have four
> digits. The year 0039 obscures what is trying to be read. Simply
> stating that years may not be abbrivated by dropping the centry is
> sufficent for what you want.
>
> 29. Section 7.5: Please provide a n example of a date dropping the
> year. Is this 03-15 or -03-15? What is the iteraction of this with
> comment 28 above?
>
> 30. Section 7.5: Qualify the comment on BCE as refering to the
> Gregorian and Julian calanders only.
>
> 31. Section 7.5: I suggest changing weekly to daily. Weekly would
> indicate a number of 1 to 53 for me and refer to the weeks of a year.
>
> 32. Section 7.5: in weekly, why is it not nThh.mm.ss?
>
> 33. Section 7.5: no discussion exists on when the prefix tag is needed
> and when it is not needed. In other locations the yearly prefix appears
> to be missing (i.e. <change><date>2003-09-11</date></change>
>
> 34. Section 7.5: Is the hh in the time field based on a 24 hour clock
> or a 12 hour clock? Is there ever a need to make this field based on
> UCT (GMT) time rather than local time?
>
> 35. Section 7.5: I have a problem with your named time syntax. What I
> expect is not what is demonstrated. Issues: 1. Is the tilda character
> actually allowed. 2. Are the parens necessary or just window dressing?
>
> 36. Section 8: titlePage is not allowed in the osis element according
> to the schema.
>
> 37. Section 9: The first div element should occur after the titlepage
> if on exists else the header.
>
> 38. Section 9: I would suggest removing the "ok-ness" of <div
> type="chapter"/> as this makes an implementer's life harder. Use a
> single method of doing things an more people get it right.
>
> 39. Section 10: Verse Esth.4.13 is missing a <q> and has a ". (ends in
> Esth.4.14)
> Verse Esth.4.16 hash both <q> and ".
> NOTE: This breaks the statement that nesting is
> nice.
>
> 40. Section 12.1.1: Example does not demonstrate the point being made.
> I think you needed to add some <p> markers or get a different item.
>
> 41. Section 12.4: Need either <q> or <speech> for Acts.7.3
> Delete " start of Acts.7.4
> speech needed for Acts.7.6 (god spoke)
>
> 42. Section 12.7: I think yo mean to say 'simply n="24" ' since you are
> dealing with a line break not a page break.
>
> 43. Section 13.10: I believe that you need to separate the two examples
> (acts and dan). Additionally the acts version is missing a <verse/>.
>
> 44. Section 13.13: Please add text on the three types used in quotes.
> (initial, medial & final)
>
> 45. Section 14: example using the reference does not have a /> on the
> end of the reference.
>
> 46. Section 14.1: in the last sentence, I suggest putting quotes around
> the two items since the command and trailing period are confusing to
> look at.
>
> 47. Section 14.6: The example has "josephus-war:loeb:245.22" as an
> osisID, but this is an illeagal id. Only one : is allowed. Should be
> "josephus_war_loeb:245.22" Question: Pattern seems to only allow _ not
> -. Is this correct? (hyphen is not a N or an L or a _)
>
> 48. Section 15.1: I like the fact that s is provided, however it needs
> to have a second parameter, the occurrence to find. I.e. find the 3rd
> occurrence of "the" in the text.
>
> 49. Section 15: Can I combine both ! And @ in a single reference? If so
> what is the order -- not specified. (order is : ! @ based on the
> schema)
>
> 50. Schema: From the schema it appears that Fred..3 is a legal
> reference. I believe you have two * in a row when you meant to have a +
> then a *
>
> 51. Section 16: It states that a reference can state what versification
> scheme is used. But this does not seem to be true based on anything
> that I have seen either in the schema or in the text.
>
> 52. Section 17.1.1: Based on the requirements in this section, the
> sample document in section 4 is not a valid OSIS document. [Missing
> creator, date in word. Missing revision element.
>
> 53. Section 21.2: Gen. is not a valid main part of an osisID. (ditto
> section 22.2)
>
> 54. Section 29.1.1: Where is the prefix en: suppose to be going? This
> is not good to put into a work short name.
>
>
> Grammer And Spelling: -- feel free to ignore these.
>
> 1. Section 2: "Many such program are" --> "Many such programs are"
> 2. Section 3: "of this kinds is" --> "of this kind is"
> 3. Seciton 6: "overidden" --> "overridden"
> 4. Section 6: "judgements" --> "judgments"
> 5. Section 7.2: "hypens" --> "hyphens"
> 6. Section 7.2: "declaring a short name, and using it later as a
> prefix, is very" (added a comma after name)
> 7. Section 7.3.4: "Date elements in the" --> "Date element in the"
> There is only one element even if it occurs multiple times.
> 8. Section 7.3.5: "indentify" --> "identify"
> 9. Section 7.3.5: "one publisher, and" -- inserted a comma.\
> 10. Section 7.3.7: "occcur" --> "occur"
> 11. Section 7.3.14: "have been prepared" --> "has been prepared"
> 12. Section 7.4: "The six elements already described" There is no
> reference to what six elements are to be noted and there were more than
> six elements just described.
> 13. Section 7.5: "string (include any leading underscore) is" as text is
> written _~5000 seems to be legal.
> 14. Section 7.5: "the the" --> "the"
> 15. Section 7.5: "chgronological" --> "chronological"
> 16. Section 10: "First" --> First"
> 16a. Section 10: "meanining" --> "meaning"
> 17. Section 11: "would appears as" --> "would appear as"
> 18. Section 12.1.2: "For example (RSV):" --> "For example:"
> 19. Section 12.3: (I don't have my NRSV handy to check this one) "lilly"
> -> lily" (twice)
> 20. Section 12.4: "repesented" --> "represented"
> 21. Section 12.4: "occassion" -> "occasion"
> 22. Section 12.5.2: "poety" -> "poetry"
> 23. Section 12.6.3: "imortant" -> "important"
> 24. Section 12.6: "dicitonary" -> "dictionary"
> 25. Section 12.6.1: "valuess" -> "values"
> 26. Section 12.7: "simpley" ---> "simply"
> 27. Section 12.7: "setting attribute" --> "setting the attribute"
> 28. Section 13.4: "chose" --> "choose"
> 29. Section 13.4: "diplay" -> "display"
> 30. Section 13.12: "divineName Different forms" --> "divineName.
> Different forms"
> 31. Section 13.14: "lilly" --> "lily"
> 32. Section 13.15: "Aplified Bible" --> "Amplified Bible"
> 33. Section 13.16: "commets" --> "comments"
> 34. Section 13.17: "tranliteration" --> "transliteration"
> 35. Section 14: "refererence" --> "reference"
> 36. Section 14: "for for" --> "for"
> 37. Section 14.2: Either "Apostolic Fathers" or "apostolic fathers"
> 38. Section 17.1.1: "actualy" --> "actually"
> 39. Section 17.1.4: "Blble" --> "Bible"
> 40. Section 18: "Implementors" --> "Implementers" (twice)
> 41. Section 20.1: "borad" --> "broad"
> 42. Section 20.2.1: "mediatation" --> "meditation"
> 43. Section 20.2.1: "studyguide" --> "study guide"
> 44. Section 20.2.6.2: "this enumerations" --> "these enumerations"
> 45. Section 20.2.7: "columnMarks" --> "column Marks"
> 46. Section 20.2.11: "tites" --> "titles"
> 47. Section 21: "adventerous" --> "adventurous"
> 48. Section 21.3: "and other are not" --> "and others are not" (ditto
> section 22.3)
> 49. Section 22: "addiional" --> "additional"
> 50. Section 22.4: "mimimum" --> "minimum" (twice)
> 51. Section 22.4: "brakets" --> "brackets" (twice)
> 52. Seciton 22.4: "limiation" --> "limitation"
> 53. Section 23: "responsiblefor" --> "responsible for"
> 54. Section 31: "othe" --> "other"
>
>
>
> _______________________________________________
> osis-editors mailing list
> osis-editors@bibletechnologieswg.org
> http://www.bibletechnologieswg.org/mailman/listinfo/osis-editors
>
--
Patrick Durusau
Director of Research and Development
Society of Biblical Literature
Patrick.Durusau@sbl-site.org
Chair, V1 - Text Processing: Office and Publishing Systems Interface
Co-Editor, ISO 13250, Topic Maps -- Reference Model
Topic Maps: Human, not artificial, intelligence at work!