UPDATED -- Re: Stage 3 proposing for issue #253: Indexing changes

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

Drat; pressed "Send" too soon. See additional comments for page 13 below.

1. Page 6: Not sure if this is important, but the documentation element for indexterm and the one that was deleted for index-base both have a "Category: Miscellaneous elements" at the end. Does that belong here as well?
   <kje>I think we'll need to update the <a:documentation> elements in the RNG files AFTER we've frozen the content of the short descriptions and the ways that we group elements in the spec. Thanks for bringing this up, and I've added it to list of spec work items that we need to remember. I've also sent a note to the TC list</kje>
   
2. Page 6: shouldn't there be a <a:documentation> element here to define the use of index-see-also, as you have with index-see?
   <kje>I've added one with some placeholder content.</kje>
   
3. Page 8: I'm not sure why the <index-sort-as> was listed here as an asset to the translation, but should it be replaced by <sort-as>, rather than removed outright?
   <kje>I think we just just remove it; it's NOT an asset to translation. Also, I suspect that this short description will be edited before DITA 2.0 is released; it's way TOO LONG!</kje>
   
4. Page 12: Various comments
   <kje>In the short description: I've corrected the places where the <xmlelement> improperly contained the word "element". Many thanks for noticing that.</kje>
   <kje>In the "Usage information": I've added the missing space. Many thanks for noticing that.</kje>
   <kje>I've implemented all the changes that you recommended vis-a-vis consistent tense and usage of the term "<prolog> element."</kje>
5. Page 13: So to clarify for myself, earlier (pg 10) you said an author might want to sort <data> under both D and <. If that was the case, they would need two separate indexterm elements, each with its own <sort-as>?
   <kje>I'll add a draft comment, so that we can address this point when we review the full content of the spec that concerns indexing. I'd like to get this proposal through the pipeline, and I think the question will be better handled as part of a fuller review.</kje>
   
6. Page 13: actually I think it should be Universal attribute group and the attributes defined below?
   <kje>Yes, the link to universal attribute group was not included because the "Universal attributes" topic is not referenced in the DITA source for this proposal. I'll see if I can correct this easily.</kje>
   

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 7/18/2019 8:24 AM, Kristen James Eberlein wrote:

Hi, Dawn. Thanks for your very thorough and excellent review. Here are responses to your comments:

1. Page 6: Not sure if this is important, but the documentation element for indexterm and the one that was deleted for index-base both have a "Category: Miscellaneous elements" at the end. Does that belong here as well?
   <kje>I think we'll need to update the <a:documentation> elements in the RNG files AFTER we've frozen the content of the short descriptions and the ways that we group elements in the spec. Thanks for bringing this up, and I've added it to list of spec work items that we need to remember. I've also sent a note to the TC list</kje>
   
2. Page 6: shouldn't there be a <a:documentation> element here to define the use of index-see-also, as you have with index-see?
   <kje>I've added one with some placeholder content.</kje>
   
3. Page 8: I'm not sure why the <index-sort-as> was listed here as an asset to the translation, but should it be replaced by <sort-as>, rather than removed outright?
   <kje>I think we just just remove it; it's NOT an asset to translation. Also, I suspect that this short description will be edited before DITA 2.0 is released; it's way TOO LONG!</kje>
   
4. Page 12: Various comments
   <kje>In the short description: I've corrected the places where the <xmlelement> improperly contained the word "element". Many thanks for noticing that.</kje>
   <kje>In the "Usage information": I've added the missing space. Many thanks for noticing that.</kje>
   <kje>I've implemented all the changes that you recommended vis-a-vis consistent tense and usage of the term "<prolog> element."</kje>
   

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 7/8/2019 10:29 AM, Dawn Stevens wrote:

My comments attached.

ïOn 7/2/19, 11:15 AM, "Kristen James Eberlein" <kris@eberleinconsulting.com> wrote:

    Proposal attached.
    
    Note that I currently am working on a large-scale overhaul of the 
    indexing element reference topics, largely moving content to the 
    architectural topics -- However, that should not affect this proposal.
    
    -- 
    Best,
    Kris
    
    Kristen James Eberlein
    Chair, OASIS DITA Technical Committee
    Principal consultant, Eberlein Consulting
    www.eberleinconsulting.com
    +1 919 622-1501; kriseberlein (skype)