MHonArc v2.5.0b2 -->
dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Indexterm: page ranges
Thanks to
all the TC for responding at length. I'd like to respond here at the very first
topic, Erik's "GENERAL" heading on an indexterm covering a unit of content. My
difficulty in seeing indexterms this way -- apart from the fact that this is not
how readers and authors would see them -- is that XML must be well formed. There
can be only one hierarchy active. On the other hand, index entries can reflect
completely orthogonal organizations. You can have index entries that
overlap/straddle each other or their parent nodes. There is no reason to
assume that an index entry range can exist within well-formed XML.
Indeed, an index range that merits its
own container may face an ontological problem: according to Microsoft's manual
of style, it should not exist. Such a sustained discussion can merit its own
topic or should otherwise belong only in the table of contents. If it is part of
the overall document structure, it probably is a candidate for the TOC, not the
index. Readers use the index for other information.
Here's a
concrete example. Suppose I wrote a task on how to change my car's spark
plugs. The sequence goes something like:
- I talk
about gapping and prepping the new spark plugs here. I describe how to use the
anti-seize compound in loving detail.
- I talk
about removing the old spark plugs. I describe use of my socket extension and
then my torque wrench.
- I talk
about inserting the new spark plugs here. I caution about getting anti-seize
compound in the wrong places. I mention my socket extension
again.
- I describe
tightening the new spark plugs using my torque wrench in excruciating
detail.
Suppose I
want my reader to be able to look up where auto tools are used in my new
masterpiece "Auto Misrepair for Dummies" book that incorporates this task. Using
pseudo-XML notation, the relevant index entry ranges go
like:
<anti-seize compound><socket
extension><torque wrench>
</anti-seize compound></socket
extension></torque wrench>
Apart from
the fact that these ranges completely overlap each other, they also cross the
task <step> element boundaries and child elements of <step>:
cmd, info, substeps, tutorialinfo etc. Human languages are such annoyingly
undisciplined things. That is why I felt compelled to propose page range
start/end markers outside of the XML structure.
There are
few other things I want to cover from the discussion on page
ranges:
- A page
range does not imply that the entry is the primary entry. It only implies
length. Otherwise, an entry that contains many page-range references
cannot tell us which one is primary. People sometimes indicate primary
entries by setting the page number reference in bold. My colleague uses an
entry like "XYZ, About" to similarly indicate it is primary. I did not
address the ability to indicate a primary entry in the original proposal:
is this a desirable feature apart from the page range
issue?
- Page
ranges do not merely mean multiple occurrences of the term. The Chicago Manual
of Style distinguishes between a continued discussion (e.g., 34-36) and
individual references on a sequence of pages (e.g., 34, 35, 36). The ability
to combine index entry references is not a substitute for explicit page
ranges.
- I
understand the concerns regarding topic-spanning indexterms. I would like to
point out that the current proposal disallows page range markers from starting
in one topic and ending in another. For topic spanning, it mentions using
indexterms at the map level and coalescing adjacent topics' indexterms. Would
people be comfortable with a proposal that only allows the map-level method of
spanning topics (i.e., jettisoning the latter alternative)? I'm talking about
Erik Hennum's description of using the start/end range markers in a map's
topicref's <topicmeta> element.
Chris