Patrick,
Here are a bunch of comments on the March version of the OSIS manual. They
fall into several different categories:
1. Typos - easy to fix
2. Requests for additional information to be included in the document.
3. Misunderstandings or questions about how things are suppose to work.
People on the osis-user list might want to scan and make comments on items
they think fall into category 3.
Jim Schaad
August Cellars Winery.
Comments on the 2.1.1 OSIS manual
1. Appendix L.1.1 references osisWordID rather than osisIDWork.
2. The sample for xsi:schemaLocation is incorrect.
www.bibltechnolgologies.net is incorrect. Also the xsd path does not
include the /OSIS/ at this point.
3. The sample does not declare the versification scheme using an existing
item. Is "Bible" considered to be a versification scheme? if so it should
be documented. Additionally the paragraph should state the name of the
attribute that his used for this.
4. The example on canonical is confusing. The effect would be the same if
you did not set the canonical attribute as what you currently have. I think
that this would be more informative to leave as missing and then say why the
title is not considered to be part of the canonical text.
5. I would like to see an Attributes allowed on XXXX section added to each
element description.
6. I suggest in section 6.1 you give an example dealing with the first of
December rather than the 25th. This gives weight to the question of having
the exact number of digits (i.e. 1999.12.01 vs. 1999.12.1)
7. Section 6.2 should more clearly define what the scope of uniqueness for
osisWork identifiers. For example, are they required to be unique only
within a single osisText element? Or within the osis element? (i.e. if you
use osisCorpous are they required to be unique in the file?)
8. I suggest renumbering section 6.3 as section 6.2.1 since this is an
attribute on the work element. Similar re-numbering would be done on
descriptions of attributes for specific elements throughout the document.
9. Examples in section 7 use type " Gregorian" as a date format, but
section 7.2.4 says that only ISO has a defined date format. If you are not
using the ISO format for dates however, I think it is strange to state that
these are ISO dates. This is based on the reading of Wikipedia 8601 article
and the date representation used for revisions. I really would like this to
be consistent.
10. Section 7.2.7 - typo - "encodes he nature" - should be 'the'
11. Section 7.2.15.1 - what does it mean for the order of items to be in
canonical order? I think it makes much more sense to state that it should
be in the order of the document and one needs to look in each section if one
is looking for a specific item. This is especially egregious if one is not
looking at a canonical book or using a canonical reference system.
12. Section 7.2.15.1 - should there be one for each reference system used in
the document? Can you use multiple reference systems and have different
scopes one for each item? or is a single scope item suppose to cover all
text included?
13. Section 7.2.15.5 - I want a lot more information on this. How does it
help to refer to another work if that work has no basic information in it
about the reference system. For example - what is the reference system used
by the example in section 4. First the case does not match between the
osisID and the refsystem pointer. Secondly is the refSystem the same as the
versification or not? This is stated as true, but the value "Bible" used in
the example is not a well defined versification system. Finally what does
it mean for the refSystem to be self-referential? (I.e. it is defined in the
work) How does a parser figure out what the reference system used is?
14. Section 7.3 - When can the yearly. be dropped? Does the ~ occur before
the yearly. or after it?
15. Section 7.3 - I don't care for the fact that yearly is used for too
purposes. What would you consider for yearly.0003 - is that for the first
or the last format?
16. Section 7.3 - I was expecting weekly.n to be for weekly readings and
thus have a value from 1 to 53 rather than days of the week. (i.e. one for
each week of the year.
17. Section 7.3 - You are using the '~' in the "wrong" place for
T~(Vespers) according the preceding definition, where the ~ precedes the
entire time string.
18. Section 7.3 - Are the parens required if a named time is used?
19. Section 7.3 - Is the list of named time exhaustive or not? The text
implies that it might allow for additional items.
20. In section 7.5 - The div type does not seem to have <head> as an
element, but it is in the examples. I assume these are supposed to be
<title>
21. In section 7.5 - you list tableofContents as one of the types for a div
element. Is this expected to be machine built or human built at this point?
22. In section 8.2 - The example and the description of the attribute 'who'
seem to conflict with each other. In the description its says you use
<speaker> if the speaker is stated, and who if the speaker is not. Yet
the
example has an explicit speaker and uses the who element. I also don't
care for the encoding rule. Use of who always makes things much easier on
scripts.
23. Examples are missing in section 8.2
24. Section 8.3 - Typo in item #5 - "Which on is used" --> 'Which one..."
Is this which encoding method or which is used by the XSLT
script?
25 Section 8.5.5 - I am unsure if you mean to have the xml text along with
the rendering. For this section it would appear that you do since you talk
about the existence of the <p> element and that cannot be seen from the
rendering.
26 Section 11.1.1 - I think you should add the <signed> element to the
example encoding to avoid confusion on people looking at the next section.
27 Section 11.3 - The final example should include the speaker or who
element along with the transChange element. Does the speaker element
surround the transChange or visa versa or does either work? (or neither -
speaker does not allow for the transChange element)
28 Section 11.4 - Example at the end of the section is a poor one,
paragraphs are not milestoneable so there is no decision to be made here
between p and q.
29 Section 11.4 - Nested speeches? - i.e. In Gospel of Mary - Mary starts
a speech which quotes the Savior for about 10 paragraphs. The Mary one is a
speech but is the Savior one? I would say yes because of length and type of
discourse.
30. Section 11.4 - need a commentary on inserting medial marks in speeches.
It would be nice if this was done exactly the same as for quotes.
31. Section 8.2 - If I use a medial type on a quote, what do I put in to
tie it to the start and end quote milestones. mID?
32. Section 11.5.2 - Need to give me information on what attribution,
doxology and refrain type values are.
33. Section 11.6.5 - Text refers to level1 but example contains index1.
34. Section 13.2 - Is it suggested that abbr should occur at every location
where an abbreviation is made? I would have thought that this element, like
the <see index> elements occurred once someplace. It seems bad news in
some
respect to have to mark w/ the expansion every abbreviation with the
expansion attribute.
35. Section 13.7 - Are TOCs done w/ the index attribute? I am thinking of
a TOC of Figures as an example. If so should there be a standard way of
representing the difference between prefixed indexes vs. post-fixed indexes.
Also is there a way to order the indexes and the location of indexes? I.e.
I can say place the following index at this point.
36. Section 13.7 - Text needs to state that level1 and index are required
attributes on the index element.
37. Section 13.9 - I don't understand what mentioned is used for. Can you
give me some clarification so that I can suggest a better set of text?
38. Section 13.17 - typo in example - missing double quote.
|
