Consider the following DITA map:
The index range begins with the start of the first topic title in
-
Eliot, I disagree. If the map is a submap that is consumed by a larger publication (for - example, a map of examples of using keys), I think the default range boundary of "end of the - map" might be entirely appropriate.
- -The index range begins with the start of the first topic title
+ in
The information developer wants an index entry that will span
-
This markup specifies that the index range begins with the start of the topic title, and
the end of the range is the end of the
The information developer could have included an end element (for example,
-
I think this rule has the same problem as for ending the range at topic body - boundaries: it means you couldn't start a range in one topic's prolog and end it in - the prolog of another sibling topic.
-That would be a hard thing to manage so probably not a realistic use case, so I can - see an argument that prolog-defined ranges span the effective topic tree rooted at - the topic with the prolog. But there's no particular reason to impose the - constraint.
-That is, a processor that can handle index ranges can also detect when a range is - started in a topic prolog but not ended in one and report the case.
-In the following code sample, the index range begins at the start of the second paragraph - and continues to the beginning of the last paragraph. If the end element was not - present, the index range would end at the end of the topic.
+In the following code sample, the index range begins at the + start of the second paragraph and continues to the beginning of the + last + paragraph.
Given the following
A processor treats the
A processor
A processor generates the following index entries:
+A processor
The following elements contain information that processors use to generate indexes.
+The following elements contain information that processors
How the index elements are combined, the location of
How the index elements are combined, the location of
+
Here are some definitions:
+While DITA provides several elements that support indexing, how those elements are used + will vary by implementation.
+While DITA itself defines markup for indexing and specifies
+ exactly what point an
The following list includes some of the conditions that + implementations might want to be aware of when considering how to + generate an index:
The nesting of
The nesting of
The start of an index range is indicated by an
The end of a range is indicated by whichever of the following occurs first:
-The applicable scope boundary depends on the location of the start element:
+The start of an index range is indicated by an
+
The end of an index range is indicated by an
+
The location of the
+
I'm not sure I agree with this rule. If I start a range in one topic body - and end it in another topic body and the two topics are presented in a - sequence such that the second topic follows the first I would expect the - range to span from the first topic to the second.
-So the rule is at least dependent on the presentation context--in a - continuous presentation there's no reason to impose boundaries, but in a - chunked presentation there might be.
-I think there's an unstated assumption that indexes are rendered for - paged media where page numbers make sense but that's not a necessary - condition--for example, I could have chunked HTML output that includes - knowledge of the page numbers the content is rendered on in some other - paged rendering (i.e., the printed version of municipal code, where the - page numbers are captured in an element-to-page-number mapping and the - HTML rendering of the same content, where the page numbers are included - as literal or meta data in the HTML pages).
-Comment updated on 19 August 2019:
-FYI, these rules have been in the DITA spec since DITA 1.1, when the
-
Hopefully all references to "page numbers" have been changed to the more - neutral term "locator".
-Eliot, I think that for your use case, the appropriate markup would be to - index in the map. Per the processing outlined in this draft, the range - should begin at the start of one topic and end at the end of the other - topic.
- -For example, given the following map, the generated index entry should be
- "test, x- y", where x = the title of
-
FYI, this is the markup for the map for the indexing content, with the - start and end elements added.
-Whichever of the following occurs first:
-Processors that support index ranges
Can we improve the phrasing of the two above list items? + Robert and I think that they were authored in order to + communicate that if you want a range to be specified for a + secondary entry, it has to be done like this:
+The
Generated index entries should not contain both locators and redirections. Therefore, - it is an error if the following conditions occur:
-An
For example, topics referenced by the master map include the following - markup:
-An
For example, a topic contains the following
-
A processor
Context = Normative statement about "An
Because we emphasize "MAY", it also means that it "may not". I would like to ask "Who - are we leaving the decision up to?"
-Is this instead a question of "SHOULD"?
-I think SHOULD is better too
-I think we cannot make this a stronger statement here than
Reminder for people to review the following material when considering any spec - statement that contains RFC-2119 terminology:
-This gives an author the flexibility to sort an index entry in an index differently from
- how its text normally would be sorted. The common use for this is to disregard
- insignificant leading text, such as punctuation or words like "the" or "a". For example,
- the author might want
Comment from Dawn Stevens - during the stage three review of proposal #253, "Indexing changes":
So .. an - author might want to sort <data> under both D and <. If that was the case, - they would need two separate indexterm elements, each with its own - <sort-as>?
I think we need to clarify the above paragraph, but I think it - will be better done as part of a targeted review of all spec content about indexing, - rather than as part of the review for this proposal.
Certain languages have special sort order needs. For example, Japanese index entries - might be written partially or wholly in kanji, but need to be sorted in phonetic order - according to its hiragana/katakana rendition. There is no reliable automated way to map - written to phonetic text: for kanji text, there can be multiple phonetic possibilities - depending on the context. The only way to correctly sort Japanese index entries is to - keep the phonetic counterparts with the written forms. The phonetic text would be - presented as the sort order text for indexing purposes.
+This gives an author the flexibility to sort an index entry in
+ an index differently from how its text normally would be
Certain languages have special sort order needs. For example,
+ Japanese index entries might be written partially or wholly in kanji,
+ but need to be sorted in phonetic order according to its
+ hiragana/katakana rendition. There is no reliable automated way to
+ map written to phonetic text: for kanji text, there can be multiple
+ phonetic possibilities depending on the context. The only way to
+ correctly sort Japanese index entries is to keep the phonetic
+ counterparts with the written forms. The phonetic text would be
+ presented as the
Comment by Eliot Kimber:
-I think we need a general discussion of index processing and rendering that covers:
-The current writeup reflects a lot of unstated assumptions about how index processing does or - should work, obviously reflecting how IBM's tools worked (and work today). These assumptions - need to be surfaced.
-We need to clearly state our assumptions, but I think we need to be careful about specifying - expected processing too precisely:
-It would be good to be upfront about the fact that many details about index generation will be - implementation specific.
-