OASIS Darwin Information Typing Architecture (DITA) TC

 View Only
  • 1.  Indexterm: page ranges

    Posted 10-03-2005 21:33
     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