[osis-editors] Review of 2.0.1 User's Manual - Draft

[Jim Schaad]

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"