dita — archive

[Kristen Eberlein]

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.