Re: [dita] Feedback: Rework on index content

[Kristen James Eberlein <kris@eberleinconsulting.com>]

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.