[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: review of indexing best practices
Here is my review of the indexing best practices document at http://www.oasis-open.org/committees/download.php/20479/092606%20Best%20 Practice%20for%20Indexing%20DITA%20topics_jth.doc Example 2 is too confusing with "topic-based authoring" being used at the text for both a primary and secondary term. I disagree with the suggestion made in example 4 in that I would strongly council that the indexterm for a section not precede the title of the section (if any). Putting the indexterm before the title makes it harder visually when reading the source and can affect some structured editors' attempt to make "bookmarks" or dynamic "tables of contents". I would either change this example to replace "section" with something else that cannot take a title or to add a "title" to this example and show the indexterm following (or within) the title element. Both examples 3 and 4 (as well as example 2) seem to me to be examples of: Insert block-level index tags immediately following the start tag of the applicable containing block element. They do not seem to me to be appropriate examples of: Insert a sentence-level index tag immediately preceding the sentence in which the text occurs. Example 5 says it shows a definition list item, but it doesn't. Instead it shows a <dd> element. Regardless, it shows the <dd> in the midde of text which is not valid. (Neither would a definition list item be valid in the middle of text.) We shouldn't show examples that are clearly invalid DITA. Furthermore, even if example 5 were valid, it would seem more suited to be an example of: Insert block-level index tags immediately following the start tag of the applicable containing block element. than what it's supposed to be which is: Insert word or phrase-level index tag immediately preceding the text to which it applies. Example 6 doesn't really do a good job of motivating or explaining what it's supposed to, which is: Avoid relocating an index tag within a text that has not changed since the last translation when you have pointed to a specific word or phrase in the text. but I'm not sure how best to create such an example without also showing what it looked like the last time there was a translation. paul
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]