OASIS Darwin Information Typing Architecture (DITA) TC

 View Only
  • 1.  RE: [dita] Are indexterm ranges backwards incompatible?

    Posted 08-15-2006 18:37
    
    
    
    
    


  • 2.  Re: [dita] Are indexterm ranges backwards incompatible?

    Posted 08-15-2006 18:45
    
    
      
      
    
    
    wouldn't a cleaner solution to be to allow
    indexterms in titles?

    JoAnn Hackos wrote:

    Unfortunately, there is no way for me to indicate an index term that applies to the title of a topic, since index term is not allowed in title. I have to use the prolog instead to point to the topic title or short description. So the second bullet item below will not work. I don’t want to have to insert the index term in the first body paragraph, which might appear on a different page from the title.

    I want to use indexterm range elsewhere, of course, and don’t want the behavior constrained in a manner that I don’t expect.


    JoAnn

    JoAnn T. Hackos, PhD
    President
    Comtech Services, Inc.
    710 Kipling Street, Suite 400
    Denver, CO 80215
    303-232-7586
    joann.hackos@comtech-serv.com
    joannhackos Skype

    www.comtech-serv.com


    From: Dana Spradley [mailto:dana.spradley@oracle.com]
    Sent: Tuesday, August 15, 2006 12:18 PM
    To: Chris Wong
    Cc: ; Grosso, Paul; dita@lists.oasis-open.org
    Subject: Re: [dita] Are indexterm ranges backwards incompatible?

    What if we look at this new feature as throwing a switch?

    If a writer doesn't make use of it, and refrains from inserting even one ranged indexterm into a book, then they get 1.0 pointwise processing.

    If, however, a user inserts even one ranged indexterm into a book, then the ambiguity inherent in their legacy indexterms is resolved as follows:

    • indexterms that appear in the body of the text are considered pointwise. If they aren't, then the writer needs to insert new start attributes and end elements into the body of the text.
    • indexterms that appear in topic metadata are considered to apply to the topic as a whole, and as such generate a page range in the index entry that corresponds to the page range of the topic. If the writer doesn't like this, they need to go in and move the offending indexterms to the most appropriate point in the body of the text.


    Dana


    Chris Wong wrote:

    "A distinction is sometimes made between continued discussion of a subject (index, for example, 34-36) and individual references to the subject on a series of pages (34, 35, 36). " -- 17.9, Manual of Style

     

    I'd say that the difference between a page range indexterm pair and a series of individual indexterms would make that distinction. Never assume that the page references should be combined.

     

    I'd ask whether clarifying an ambiguity in the standard is incompatible. If we strive to cater to every possible interpretation of any ambiguity in the spec, we'd drive ourselves batty. I'm of the opinion that our spec really says what the user can do and makes no attempt at a comprehensive list of what a user cannot do. The latter would need an inconveniently large truck to hold the resulting document. So if a user writes DITA and expects processing behavior that the standard does not expressively support, that user should not expect that nonstandard behavior to be implemented by everyone. Indeed, expecting an unpromised feature of DITA would easily lead to interoperability problems even within a DITA version, let alone across versions.

     

    As I see it, this is probably not that big an issue because the XML itself will continue to be valid, and the user can continue to use legacy processing. Such XML cannot interoperate across DITA 1.0 implementations anyway.

     

    Chris


    From: [mailto:joann.hackos@comtech-serv.com]
    Sent: Tuesday, August 15, 2006 1:47 PM
    To: Grosso, Paul; dita@lists.oasis-open.org
    Subject: RE: [dita] Are indexterm ranges backwards incompatible?

    I would not agree with the result assumptions. What mechanism exists for the numbers 5, 6, 7, and 8 to be concatenated into a range 5-8?  A continuous discussion ranging over pages 5-8 does not mean the same as points referenced by the number 5, 6, 7, and 8. The indexer should be solely responsible for determining when a range of pages is used, not have some automatic decision made.

    JoAnn

    JoAnn T. Hackos, PhD
    President
    Comtech Services, Inc.


    303-232-7586
    joann.hackos@comtech-serv.com
    joannhackos Skype

    www.comtech-serv.com


    From: Grosso, Paul [mailto:pgrosso@ptc.com]
    Sent: Tuesday, August 15, 2006 11:21 AM
    To: dita@lists.oasis-open.org
    Subject: RE: [dita] Are indexterm ranges backwards incompatible?

    I generally agree with Bruce here.

     

    But I also need to take issue with:

     

    new ranged indexterms they add would cause these old point indexterms to be misinterpreted

     

    With our existing indexterm markup, you cannot distinguish between use of indexterms and ranges by looking at the resulting index. An indexterm marks a point, and the page on which that point falls will be included in the resulting index. An index range marks a start and end point, and all pages starting with the one on which the start point falls and ending with the one on which the end point falls will be included in the resulting index.

     

    Unless one has a fancier indexing process whereby one can, say, request a bold page number in the index for the most important reference and italic page numbers for pages on which there are related figures, etc., there is no distinction among page numbers in the resulting index.

     

    Looking at the resulting index, one cannot tell if index-page-range markup was used to create that index or not. A resulting index entry of:

     

    cheese  2, 5-8, 12

     

    could have been generated by pointwise indexterm markup throughout the source that just so happened to end up being points on pages 2, 5, 6, 7, 8, and 12.

     

    paul

     


    From: Esrig, Bruce (Bruce) [mailto:esrig@lucent.com]
    Sent: Tuesday, 2006 August 15 11:53
    To: Dana Spradley
    Cc: dita@lists.oasis-open.org
    Subject: RE: [dita] Are indexterm ranges backwards incompatible?

    On the other hand, Dana,

     

    This logic could be applied to outlaw any extension, since every user would have to review every document to determine whether they had intended to use the extension.

     

    With DITA 1.1, we clarify that an indexterm designates a point at which to start reading about the indexed subject. The DITA 1.1 conceit is that this was true all along. In DITA 1.0, this aspect of the interpretation was unspecified because there was no way to specify anything else. But if it even makes sense to take sides on this, it's possible to argue that the default disambiguation is the DITA 1.1 way. Indexing practice typically presumes that an index entry refers to a point at which to start reading.

     

    For those who wish to specify a range of pages possibly not starting at the top of a topic, a new capability is provided that permits such a specification. The specification of a range generates a page range in outputs that have page numbers, such as PDF files. In other outputs, it generates a reference to the start page only.

     

    Best wishes,

     


    From: Dana Spradley [mailto:dana.spradley@oracle.com]
    Sent: Tuesday, August 15, 2006 12:41 PM
    To: dita@lists.oasis-open.org
    Subject: [dita] Are indexterm ranges backwards incompatible?

    After this morning's meeting, I'm starting to think that maybe ranged indexterm should be considered backwards incompatible with DITA 1.0.

    In 1.0, it is ambiguous whether indexterms point to discussions confined to a single page, or to extended discussions that begin on a certain page.

    Introducing ranged indexterms removes that ambiguity.

    Users who want to make use of ranged indexterms would need to go back through their entire document set and replace current point indexterms with ranged indexterms where appropriate - otherwise any new ranged indexterms they add would cause these old point indexterms to be misinterpreted.

    Doesn't that amount to backwards incompatibility?

    --Dana



  • 3.  Re: [dita] Are indexterm ranges backwards incompatible?

    Posted 08-15-2006 19:46
    
    
      
      
    
    
    Actually, I don't understand this JoAnn.

    When would a topic's title appear on a different page from the first part of the body?

    --Dana

    Dana Spradley wrote:
    wouldn't a cleaner solution to be to allow indexterms in titles?

    JoAnn Hackos wrote:

    Unfortunately, there is no way for me to indicate an index term that applies to the title of a topic, since index term is not allowed in title. I have to use the prolog instead to point to the topic title or short description. So the second bullet item below will not work. I don’t want to have to insert the index term in the first body paragraph, which might appear on a different page from the title.

    I want to use indexterm range elsewhere, of course, and don’t want the behavior constrained in a manner that I don’t expect.


    JoAnn

    JoAnn T. Hackos, PhD
    President
    Comtech Services, Inc.
    710 Kipling Street, Suite 400
    Denver, CO 80215
    303-232-7586
    joann.hackos@comtech-serv.com
    joannhackos Skype

    www.comtech-serv.com


    From: Dana Spradley [mailto:dana.spradley@oracle.com]
    Sent: Tuesday, August 15, 2006 12:18 PM
    To: Chris Wong
    Cc: ; Grosso, Paul; dita@lists.oasis-open.org
    Subject: Re: [dita] Are indexterm ranges backwards incompatible?

    What if we look at this new feature as throwing a switch?

    If a writer doesn't make use of it, and refrains from inserting even one ranged indexterm into a book, then they get 1.0 pointwise processing.

    If, however, a user inserts even one ranged indexterm into a book, then the ambiguity inherent in their legacy indexterms is resolved as follows:

    • indexterms that appear in the body of the text are considered pointwise. If they aren't, then the writer needs to insert new start attributes and end elements into the body of the text.
    • indexterms that appear in topic metadata are considered to apply to the topic as a whole, and as such generate a page range in the index entry that corresponds to the page range of the topic. If the writer doesn't like this, they need to go in and move the offending indexterms to the most appropriate point in the body of the text.


    Dana


    Chris Wong wrote:

    "A distinction is sometimes made between continued discussion of a subject (index, for example, 34-36) and individual references to the subject on a series of pages (34, 35, 36). " -- 17.9, Manual of Style

     

    I'd say that the difference between a page range indexterm pair and a series of individual indexterms would make that distinction. Never assume that the page references should be combined.

     

    I'd ask whether clarifying an ambiguity in the standard is incompatible. If we strive to cater to every possible interpretation of any ambiguity in the spec, we'd drive ourselves batty. I'm of the opinion that our spec really says what the user can do and makes no attempt at a comprehensive list of what a user cannot do. The latter would need an inconveniently large truck to hold the resulting document. So if a user writes DITA and expects processing behavior that the standard does not expressively support, that user should not expect that nonstandard behavior to be implemented by everyone. Indeed, expecting an unpromised feature of DITA would easily lead to interoperability problems even within a DITA version, let alone across versions.

     

    As I see it, this is probably not that big an issue because the XML itself will continue to be valid, and the user can continue to use legacy processing. Such XML cannot interoperate across DITA 1.0 implementations anyway.

     

    Chris


    From: [mailto:joann.hackos@comtech-serv.com]
    Sent: Tuesday, August 15, 2006 1:47 PM
    To: Grosso, Paul; dita@lists.oasis-open.org
    Subject: RE: [dita] Are indexterm ranges backwards incompatible?

    I would not agree with the result assumptions. What mechanism exists for the numbers 5, 6, 7, and 8 to be concatenated into a range 5-8?  A continuous discussion ranging over pages 5-8 does not mean the same as points referenced by the number 5, 6, 7, and 8. The indexer should be solely responsible for determining when a range of pages is used, not have some automatic decision made.

    JoAnn

    JoAnn T. Hackos, PhD
    President
    Comtech Services, Inc.


    303-232-7586
    joann.hackos@comtech-serv.com
    joannhackos Skype

    www.comtech-serv.com


    From: Grosso, Paul [mailto:pgrosso@ptc.com]
    Sent: Tuesday, August 15, 2006 11:21 AM
    To: dita@lists.oasis-open.org
    Subject: RE: [dita] Are indexterm ranges backwards incompatible?

    I generally agree with Bruce here.

     

    But I also need to take issue with:

     

    new ranged indexterms they add would cause these old point indexterms to be misinterpreted

     

    With our existing indexterm markup, you cannot distinguish between use of indexterms and ranges by looking at the resulting index. An indexterm marks a point, and the page on which that point falls will be included in the resulting index. An index range marks a start and end point, and all pages starting with the one on which the start point falls and ending with the one on which the end point falls will be included in the resulting index.

     

    Unless one has a fancier indexing process whereby one can, say, request a bold page number in the index for the most important reference and italic page numbers for pages on which there are related figures, etc., there is no distinction among page numbers in the resulting index.

     

    Looking at the resulting index, one cannot tell if index-page-range markup was used to create that index or not. A resulting index entry of:

     

    cheese  2, 5-8, 12

     

    could have been generated by pointwise indexterm markup throughout the source that just so happened to end up being points on pages 2, 5, 6, 7, 8, and 12.

     

    paul

     


    From: Esrig, Bruce (Bruce) [mailto:esrig@lucent.com]
    Sent: Tuesday, 2006 August 15 11:53
    To: Dana Spradley
    Cc: dita@lists.oasis-open.org
    Subject: RE: [dita] Are indexterm ranges backwards incompatible?

    On the other hand, Dana,

     

    This logic could be applied to outlaw any extension, since every user would have to review every document to determine whether they had intended to use the extension.

     

    With DITA 1.1, we clarify that an indexterm designates a point at which to start reading about the indexed subject. The DITA 1.1 conceit is that this was true all along. In DITA 1.0, this aspect of the interpretation was unspecified because there was no way to specify anything else. But if it even makes sense to take sides on this, it's possible to argue that the default disambiguation is the DITA 1.1 way. Indexing practice typically presumes that an index entry refers to a point at which to start reading.

     

    For those who wish to specify a range of pages possibly not starting at the top of a topic, a new capability is provided that permits such a specification. The specification of a range generates a page range in outputs that have page numbers, such as PDF files. In other outputs, it generates a reference to the start page only.

     

    Best wishes,

     


    From: Dana Spradley [mailto:dana.spradley@oracle.com]
    Sent: Tuesday, August 15, 2006 12:41 PM
    To: dita@lists.oasis-open.org
    Subject: [dita] Are indexterm ranges backwards incompatible?

    After this morning's meeting, I'm starting to think that maybe ranged indexterm should be considered backwards incompatible with DITA 1.0.

    In 1.0, it is ambiguous whether indexterms point to discussions confined to a single page, or to extended discussions that begin on a certain page.

    Introducing ranged indexterms removes that ambiguity.

    Users who want to make use of ranged indexterms would need to go back through their entire document set and replace current point indexterms with ranged indexterms where appropriate - otherwise any new ranged indexterms they add would cause these old point indexterms to be misinterpreted.

    Doesn't that amount to backwards incompatibility?

    --Dana



  • 4.  RE: [dita] Are indexterm ranges backwards incompatible?

    Posted 08-15-2006 19:59
    
    
    
    
    
    When there is a long shortdesc and/or abstract and/or when the style that the user has determined (remember, the DITA spec doesn't prescribe style) has, say, the abstract start a new page.
     
    By the way, indexterms are already allowed within titles by wrapping them in a ph element.
     
    paul


    From: Dana Spradley [mailto:dana.spradley@oracle.com]
    Sent: Tuesday, 2006 August 15 14:46
    To: Dana Spradley
    Cc: JoAnn Hackos; Chris Wong; Grosso, Paul; dita@lists.oasis-open.org
    Subject: Re: [dita] Are indexterm ranges backwards incompatible?

    Actually, I don't understand this JoAnn.

    When would a topic's title appear on a different page from the first part of the body?

    --Dana

    Dana Spradley wrote:
    wouldn't a cleaner solution to be to allow indexterms in titles?

    JoAnn Hackos wrote:

    Unfortunately, there is no way for me to indicate an index term that applies to the title of a topic, since index term is not allowed in title. I have to use the prolog instead to point to the topic title or short description. So the second bullet item below will not work. I don’t want to have to insert the index term in the first body paragraph, which might appear on a different page from the title.

    I want to use indexterm range elsewhere, of course, and don’t want the behavior constrained in a manner that I don’t expect.


    JoAnn

    JoAnn T. Hackos, PhD
    President
    Comtech Services, Inc.
    710 Kipling Street, Suite 400
    Denver, CO 80215
    303-232-7586
    joann.hackos@comtech-serv.com
    joannhackos Skype

    www.comtech-serv.com


    From: Dana Spradley [mailto:dana.spradley@oracle.com]
    Sent: Tuesday, August 15, 2006 12:18 PM
    To: Chris Wong
    Cc: ; Grosso, Paul; dita@lists.oasis-open.org
    Subject: Re: [dita] Are indexterm ranges backwards incompatible?

    What if we look at this new feature as throwing a switch?

    If a writer doesn't make use of it, and refrains from inserting even one ranged indexterm into a book, then they get 1.0 pointwise processing.

    If, however, a user inserts even one ranged indexterm into a book, then the ambiguity inherent in their legacy indexterms is resolved as follows:

    • indexterms that appear in the body of the text are considered pointwise. If they aren't, then the writer needs to insert new start attributes and end elements into the body of the text.
    • indexterms that appear in topic metadata are considered to apply to the topic as a whole, and as such generate a page range in the index entry that corresponds to the page range of the topic. If the writer doesn't like this, they need to go in and move the offending indexterms to the most appropriate point in the body of the text.


    Dana


    Chris Wong wrote:

    "A distinction is sometimes made between continued discussion of a subject (index, for example, 34-36) and individual references to the subject on a series of pages (34, 35, 36). " -- 17.9, Manual of Style

    I'd say that the difference between a page range indexterm pair and a series of individual indexterms would make that distinction. Never assume that the page references should be combined.

    I'd ask whether clarifying an ambiguity in the standard is incompatible. If we strive to cater to every possible interpretation of any ambiguity in the spec, we'd drive ourselves batty. I'm of the opinion that our spec really says what the user can do and makes no attempt at a comprehensive list of what a user cannot do. The latter would need an inconveniently large truck to hold the resulting document. So if a user writes DITA and expects processing behavior that the standard does not expressively support, that user should not expect that nonstandard behavior to be implemented by everyone. Indeed, expecting an unpromised feature of DITA would easily lead to interoperability problems even within a DITA version, let alone across versions.

    As I see it, this is probably not that big an issue because the XML itself will continue to be valid, and the user can continue to use legacy processing. Such XML cannot interoperate across DITA 1.0 implementations anyway.

    Chris


    From: [mailto:joann.hackos@comtech-serv.com]
    Sent: Tuesday, August 15, 2006 1:47 PM
    To: Grosso, Paul; dita@lists.oasis-open.org
    Subject: RE: [dita] Are indexterm ranges backwards incompatible?

    I would not agree with the result assumptions. What mechanism exists for the numbers 5, 6, 7, and 8 to be concatenated into a range 5-8?  A continuous discussion ranging over pages 5-8 does not mean the same as points referenced by the number 5, 6, 7, and 8. The indexer should be solely responsible for determining when a range of pages is used, not have some automatic decision made.

    JoAnn

    JoAnn T. Hackos, PhD
    President
    Comtech Services, Inc.


    303-232-7586
    joann.hackos@comtech-serv.com
    joannhackos Skype

    www.comtech-serv.com


    From: Grosso, Paul [mailto:pgrosso@ptc.com]
    Sent: Tuesday, August 15, 2006 11:21 AM
    To: dita@lists.oasis-open.org
    Subject: RE: [dita] Are indexterm ranges backwards incompatible?

    I generally agree with Bruce here.

    But I also need to take issue with:

    new ranged indexterms they add would cause these old point indexterms to be misinterpreted

    With our existing indexterm markup, you cannot distinguish between use of indexterms and ranges by looking at the resulting index. An indexterm marks a point, and the page on which that point falls will be included in the resulting index. An index range marks a start and end point, and all pages starting with the one on which the start point falls and ending with the one on which the end point falls will be included in the resulting index.

    Unless one has a fancier indexing process whereby one can, say, request a bold page number in the index for the most important reference and italic page numbers for pages on which there are related figures, etc., there is no distinction among page numbers in the resulting index.

    Looking at the resulting index, one cannot tell if index-page-range markup was used to create that index or not. A resulting index entry of:

    cheese  2, 5-8, 12

    could have been generated by pointwise indexterm markup throughout the source that just so happened to end up being points on pages 2, 5, 6, 7, 8, and 12.

    paul


    From: Esrig, Bruce (Bruce) [mailto:esrig@lucent.com]
    Sent: Tuesday, 2006 August 15 11:53
    To: Dana Spradley
    Cc: dita@lists.oasis-open.org
    Subject: RE: [dita] Are indexterm ranges backwards incompatible?

    On the other hand, Dana,

    This logic could be applied to outlaw any extension, since every user would have to review every document to determine whether they had intended to use the extension.

    With DITA 1.1, we clarify that an indexterm designates a point at which to start reading about the indexed subject. The DITA 1.1 conceit is that this was true all along. In DITA 1.0, this aspect of the interpretation was unspecified because there was no way to specify anything else. But if it even makes sense to take sides on this, it's possible to argue that the default disambiguation is the DITA 1.1 way. Indexing practice typically presumes that an index entry refers to a point at which to start reading.

    For those who wish to specify a range of pages possibly not starting at the top of a topic, a new capability is provided that permits such a specification. The specification of a range generates a page range in outputs that have page numbers, such as PDF files. In other outputs, it generates a reference to the start page only.

    Best wishes,


    From: Dana Spradley [mailto:dana.spradley@oracle.com]
    Sent: Tuesday, August 15, 2006 12:41 PM
    To: dita@lists.oasis-open.org
    Subject: [dita] Are indexterm ranges backwards incompatible?

    After this morning's meeting, I'm starting to think that maybe ranged indexterm should be considered backwards incompatible with DITA 1.0.

    In 1.0, it is ambiguous whether indexterms point to discussions confined to a single page, or to extended discussions that begin on a certain page.

    Introducing ranged indexterms removes that ambiguity.

    Users who want to make use of ranged indexterms would need to go back through their entire document set and replace current point indexterms with ranged indexterms where appropriate - otherwise any new ranged indexterms they add would cause these old point indexterms to be misinterpreted.

    Doesn't that amount to backwards incompatibility?

    --Dana