DR 09-0196 - General: Conventions for element long names

[Shawn Villaron]

This is in regards to the JP defect report.


Nature of the Defect:

Throughout Part 1, element names are followed by more formal names, in parentheses. For example,

§17.9.3 ilvl (Numbering Level Reference)

This element specifies the numbering level of the numbering definition instance which shall be applied to the parent paragraph.

However, in the general text, these names are used lower case. Sometimes in italic. This reduces the text to gobbledygook.  Moreover, translation to the Japanese language becomes difficult. Better practice in this situation is to follow, for example, the W3C XML Schemas approach where defined terms are more clearly marked out typographically and to use hyperlinks.

Solution Proposed by the Submitter:

Element formal names should either be capitalized in normal text, since they are proper names, or they should be all italicized or in some special font weight variation, such as a demi-bold. For example:

§17.9.3 ilvl (Numbering Level Reference)

This element specifies the numbering level of the Numbering Definition Instance which shall be applied to the parent paragraph.

Note that in the following clause, the name is currently italicized:

§17.3.1.19 numPr (Numbering Definition Instance Reference)

This element specifies that the current paragraph references a <i>numbering definition instance</i> in the current document.

Indeed, all these phrases should be hyperlinks in the PDF.

This editorial change can be automated by

1.        extracting all the parenthetical phrases

2.        sorting longest first

3.        finding instances of the phrase in paragraphs and lists, and markup up the reference.

I wonder if this is really a defect report or a recommendation for consideration when we, in the future, decide to issue a revision?  This would touch the vast majority of the pages in the standard.  Do we believe that this is an actionable defect report or should we CLOSE WITHOUT ACTION the DR and reconsider the guidance at a point in time where we're doing radical editing/formatting/restructuring of the standard?

THanks,

shawn

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.vse.cz/pipermail/sc34wg4/attachments/20100318/5e5b92fa/attachment-0001.htm>