Re: [dita] Feedback: Rework on index content

[Eliot Kimber <ekimber@contrext.com>]

The spec seems clear that the @start and @end attributes are just strings that are matched, not sequences of tokens.

I agree that allowing a single start to match multiple ends or visa/versa wouldn't make much sense and would be even harder to manage than ranges are now.

Cheers,

E.

--
Eliot Kimber
http://contrext.com
 

ïOn 8/9/19, 5:24 PM, "Kristen James Eberlein" <dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com> wrote:

    Thanks tons for the detailed review. See below for my best answers. A 
    few places I honestly answered "Dunno".
    
    Best,
    Kris
    
    Kristen James Eberlein
    Chair, OASIS DITA Technical Committee
    Principal consultant, Eberlein Consulting
    www.eberleinconsulting.com
    +1 919 622-1501; kriseberlein (skype)
    
    On 8/9/2019 3:35 PM, Dr. Stanley Doherty wrote:
    > Looks good -- just a few minor questions/comments.
    > ==========================
    >
    > All page references are to the 7-30-2019 PDF distributed by Kris.
    >
    > A. Did we lose any 1.3 material in the rework.
    >     SDoherty: None that I discern. I like the updated structure.
    >
    > B. Did it make sense?
    >     SDoherty: Yes, it read well. Here are some comments and questions.
    >
    >     PDF/3 (line 5): Is there a limit on the number of nested <indexterm>
    >     levels?
    No. There might be a limit to the number of levels an implementation's 
    style sheets supports, but that's not for the spec to say anything about.
    >
    >     PDF/3 (line 40-ish): Suggest "determines" instead of "has an effect
    >     on".
    
    Done, and thanks.
    
    >
    >     PDF/3 (line 48-ish): The first sentence in "Topic prologs or DITA
    >     maps" was tough reading - at least for me. Suggest something a bit
    >     more drawn out: "In a topic <prolog>, <indexterm> is a child of
    >     <metadata> and <keywords>. In a map <topicref>, it is the child of
    >     <topicmeta> and <keywords>."
    Have now split this into two definition list entries. More word smithing 
    is needed here for sure.
    >
    >     PDF/4 (line 4): Suggest "determines" instead of "has an effect
    >     on".
    Changed to read "The nesting of <indexterm> elements and the presence of 
    redirection elements determines whether locators are rendered in the 
    generated index:
    >
    >     PDF/4 (line 45-ish): Under "Index redirection", would it be more
    >     clear to say that redirections only resolve within the scope of
    >     <indexterm>s referenced from the root scope?
    Wow. I don't think that we want to want to bring key scopes into this. 
    Or are you asking about whether <index-see> and <index-see-also> 
    elements produce a rendering in a generated index depends on whether the 
    publication contains <indexterm> elements that match the redirection?
    >   
    >     PDF/6 (line 5): Any restrictions on naming these <indexterm>
    >     identifiers?
    That does not seem right to me. I think we need to recast this content 
    thoroughly before making simple changes.
    >
    >     PDF/6 (line 5): Can I overload @start or @end with multiple
    >     values? <indexterm start="range1 range2">term</indexterm>.
    >     Multiple ranges may have the same begin or end points
    
    To me, the current info about matching @start and @end attributes is 
    very confusing. I'm probably going to suggest that we simplify what the 
    spec says about index ranges. From a practical perspective, it seems 
    insane to specify multiple values for @start and @end attributes. Do you 
    see use cases for this?
    
    >
    >     PDF/7 (line 40-ish): Suggest some sort of rewording of the
    >     paragraph "Now assume . . .." Maybe "Ranges defined in a
    >     topic <prolog> cover topics subordinate to that topic in
    >     a map branch."
    Have done a bit of reswizzling here to improve the flow.
    >
    >     PDF/10: Noticed that "multilevel" sometimes has a hyphen
    >     (multi-level).
    
    Made this consistently "multilevel".
    
    >
    >     General: What is the expected processing behavior for empty
    >     <indexterm> elements? Messed up multilevel elements?
    >     Oxygen deems this valid:
    >     <indexterm><indexterm>level-2</indexterm></indexterm>
    Dunno. It's certainly valid by the grammar files. I've seen people use 
    Schematron to trigger errors for such tagging.
    >   
    >     General: Should the @start and @end page references respect
    >     the bookmap chapter-page pagination references?
    I don't know; have not thought about that. This is the base spec, so we 
    won't be making references to bookmap. Can you phrase this in a general 
    fashion? For example, assume a bookmap generalized to map. How would the 
    scenario you are thinking of work in that context? Given the "rules" as 
    written in DITA 1.1-1.3, it might also vary based on whether the bookmap 
    uses "chapter maps". I am beginning to think we REALLY need to simplify 
    index ranges for DITA 2.0.
    >   
    >     General: Precedence question. If I have a shared topic with an
    >     <indexterm> and I reference that shared topic multiple times
    >     within the same map, should processors generate one index entry
    >     for the first time they read the shared topic? each time they
    >     ready it?
    I would think that the generated index will include locators for each 
    instance of the <indexterm> element
    >   
    >
    >     General: Should we be cross-referencing the bookmap <indexlist/>
    >     element here? FWIW I get an index by default when I run a
    >     map through the PDF2 processor, but need to add <indexlist/>
    >     manually to get an index with bookmaps.
    Base spec, so no topic for <indexlist>.
    >
    >     General: Does <index-base> deserve a mention here?
    >
    >     General: Does <index-sort-as> deserve a mention here?
    If we approve the current index changes proposal, those elements won't 
    exist in DITA 2.0
    >
    > C. Comments on processing instructions?
    >     SDoherty: None.
    >
    
    ---------------------------------------------------------------------
    To unsubscribe from this mail list, you must leave the OASIS TC that 
    generates this mail.  Follow this link to all your TCs in OASIS at:
    https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php