OASIS Darwin Information Typing Architecture (DITA) TC

Background: We removed the index from the 1.2 specification because it was of extremely low quality. Since then, Robert and I have been improving the indexing as we can (placing all <indexterm> elements in the prolog), although there still are many holes. We *can* index during the forthcoming 30-day review, and I have several folks who have volunteered to work together under rigid guidelines to do so. Shall we move forward with this? I'm old school; I firmly believe that an index is an important and necessary entry point to information, and I don't think that online search can replace it. Let's talk about this. I know that we have TC members who think that an index is unprofessional in PDF output unless the <indexterm> entries are placed in-text. -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype)

I agree that an index is important. But I also feel very strongly that if the index entries are not in line, the index should not be produced in PDF, for the simple reason that it will result in many page number references that are wrong (because they will point to the start of the topic rather than the place where the term actually occurs). Readers will not understand or care why the page number references are wrong and will assume that either we did poor job of indexing or assume that DITA's normal PDF production tools can't do indexing properly, neither of which is the case. So while having an index is important, if we can't put the index entries in the source at the point of occurrence of the terms indexed then we should not produce the index for PDF. I know from painful experience how much work it is to put index entries inline if you aren't doing it as you write. Cheers, Eliot ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/7/15, 9:00 AM, "Kristen James Eberlein" <dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com> wrote: >Background: > >We removed the index from the 1.2 specification because it was of >extremely low quality. Since then, Robert and I have been improving the >indexing as we can (placing all <indexterm> elements in the prolog), >although there still are many holes. > >We *can* index during the forthcoming 30-day review, and I have several >folks who have volunteered to work together under rigid guidelines to do >so. > >Shall we move forward with this? I'm old school; I firmly believe that >an index is an important and necessary entry point to information, and I >don't think that online search can replace it. > >Let's talk about this. I know that we have TC members who think that an >index is unprofessional in PDF output unless the <indexterm> entries are >placed in-text. > >-- >Best, >Kris > >Kristen James Eberlein >Chair, OASIS DITA Technical Committee >Principal consultant, Eberlein Consulting >www.eberleinconsulting.com >+1 919 682-2290; kriseberlein (skype) > > >--------------------------------------------------------------------- >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 > >

An index can be one of the better ways of finding things without having to take a drink out of the firehose that is search. I agree with Eliot's position on inline vs. prolog. The only index terms in the prolog should be those that correspond with the entire scope of the topic. In general (i.e., not just the spec), writing shorter tightly scoped topics increases the likelihood that index terms will be in the prolog rather than inline. Best Regards, Bob On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber < ekimber@contrext.com > wrote: I agree that an index is important. But I also feel very strongly that if the index entries are not in line, the index should not be produced in PDF, for the simple reason that it will result in many page number references that are wrong (because they will point to the start of the topic rather than the place where the term actually occurs). Readers will not understand or care why the page number references are wrong and will assume that either we did poor job of indexing or assume that DITA's normal PDF production tools can't do indexing properly, neither of which is the case. So while having an index is important, if we can't put the index entries in the source at the point of occurrence of the terms indexed then we should not produce the index for PDF. I know from painful experience how much work it is to put index entries inline if you aren't doing it as you write. Cheers, Eliot ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com > wrote: >Background: > >We removed the index from the 1.2 specification because it was of >extremely low quality. Since then, Robert and I have been improving the >indexing as we can (placing all <indexterm> elements in the prolog), >although there still are many holes. > >We *can* index during the forthcoming 30-day review, and I have several >folks who have volunteered to work together under rigid guidelines to do >so. > >Shall we move forward with this? I'm old school; I firmly believe that >an index is an important and necessary entry point to information, and I >don't think that online search can replace it. > >Let's talk about this. I know that we have TC members who think that an >index is unprofessional in PDF output unless the <indexterm> entries are >placed in-text. > >-- >Best, >Kris > >Kristen James Eberlein >Chair, OASIS DITA Technical Committee >Principal consultant, Eberlein Consulting > www.eberleinconsulting.com > +1 919 682-2290 ; kriseberlein (skype) > > >--------------------------------------------------------------------- >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 > > --------------------------------------------------------------------- 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 -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

I think it is useful to provide a quality index for the specification. As such, I also agree with Bob below. I think prolog indexterms should apply to the entire scope of the topic, while inlines should also be used when necessary. Since a lot of the spec
has been broken into smaller components, I also hope it is true that we should be able to stick with the prolog approach in general. I do not want to rule out using the inline terms, though.





Thanks and best regards,


Scott Hudson
Senior Consultant
Comtech Services Inc.

303-232-7586









From: < dita@lists.oasis-open.org > on behalf of Bob Thomas
Date: Tuesday, July 7, 2015 at 8:31 AM
To: Eliot Kimber
Cc: DITA TC
Subject: Re: [dita] Index in the PDF version of the spec?





An index can be one of the better ways of finding things without having to take a drink out of the firehose that is search.


I agree with Eliot's position on inline vs. prolog. The only index terms in the prolog should be those that correspond with the entire scope of the topic. In general (i.e., not just the spec), writing shorter tightly scoped topics increases the likelihood that
index terms will be in the prolog rather than inline.


Best Regards,
Bob


On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber
< ekimber@contrext.com > wrote:

I agree that an index is important.

But I also feel very strongly that if the index entries are not in line,
the index should not be produced in PDF, for the simple reason that it
will result in many page number references that are wrong (because they
will point to the start of the topic rather than the place where the term
actually occurs).

Readers will not understand or care why the page number references are
wrong and will assume that either we did poor job of indexing or assume
that DITA's normal PDF production tools can't do indexing properly,
neither of which is the case.

So while having an index is important, if we can't put the index entries
in the source at the point of occurrence of the terms indexed then we
should not produce the index for PDF.

I know from painful experience how much work it is to put index entries
inline if you aren't doing it as you write.

Cheers,

Eliot
----
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com




On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on

behalf of kris@eberleinconsulting.com > wrote:

>Background:
>
>We removed the index from the 1.2 specification because it was of
>extremely low quality. Since then, Robert and I have been improving the
>indexing as we can (placing all <indexterm> elements in the prolog),
>although there still are many holes.
>
>We *can* index during the forthcoming 30-day review, and I have several
>folks who have volunteered to work together under rigid guidelines to do
>so.
>
>Shall we move forward with this? I'm old school; I firmly believe that
>an index is an important and necessary entry point to information, and I
>don't think that online search can replace it.
>
>Let's talk about this. I know that we have TC members who think that an
>index is unprofessional in PDF output unless the <indexterm> entries are
>placed in-text.
>
>--
>Best,
>Kris
>
>Kristen James Eberlein
>Chair, OASIS DITA Technical Committee
>Principal consultant, Eberlein Consulting
> www.eberleinconsulting.com
> +1 919 682-2290 ; kriseberlein (skype)
>
>
>---------------------------------------------------------------------
>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
>
>



---------------------------------------------------------------------
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









--
Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype
Time zone: Mountain (GMT-7)

The problem with relying on index entries in the prolog is that even a short topic can break across a page and prolog index entries can thus end up pointing to the wrong page. Readers have no knowledge of or expectation that some index entries apply to an entire topic--they expect to find something related to the index entry on the page pointed to. Cheers, Eliot ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/7/15, 1:59 PM, "Hudson, Scott" <dita@lists.oasis-open.org on behalf of scott.hudson@comtech-serv.com> wrote: >I think it is useful to provide a quality index for the specification. As >such, I also agree with Bob below. I think prolog indexterms should apply >to the entire scope of the topic, while inlines should also be used when >necessary. Since a lot of the spec > has been broken into smaller components, I also hope it is true that we >should be able to stick with the prolog approach in general. I do not >want to rule out using the inline terms, though. > > >Thanks and best regards, > > >Scott Hudson >Senior Consultant >Comtech Services Inc. >303-232-7586 > > > > > > > >From: <dita@lists.oasis-open.org> on behalf of Bob Thomas >Date: Tuesday, July 7, 2015 at 8:31 AM >To: Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >An index can be one of the better ways of finding things without having >to take a drink out of the firehose that is search. > > >I agree with Eliot's position on inline vs. prolog. The only index terms >in the prolog should be those that correspond with the entire scope of >the topic. In general (i.e., not just the spec), writing shorter tightly >scoped topics increases the likelihood that > index terms will be in the prolog rather than inline. > > >Best Regards, >Bob > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber ><ekimber@contrext.com> wrote: > >I agree that an index is important. > >But I also feel very strongly that if the index entries are not in line, >the index should not be produced in PDF, for the simple reason that it >will result in many page number references that are wrong (because they >will point to the start of the topic rather than the place where the term >actually occurs). > >Readers will not understand or care why the page number references are >wrong and will assume that either we did poor job of indexing or assume >that DITA's normal PDF production tools can't do indexing properly, >neither of which is the case. > >So while having an index is important, if we can't put the index entries >in the source at the point of occurrence of the terms indexed then we >should not produce the index for PDF. > >I know from painful experience how much work it is to put index entries >inline if you aren't doing it as you write. > >Cheers, > >Eliot >---- >Eliot Kimber, Owner >Contrext, LLC > http://contrext.com > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" <dita@lists.oasis-open.org on >behalf of kris@eberleinconsulting.com> wrote: > >>Background: >> >>We removed the index from the 1.2 specification because it was of >>extremely low quality. Since then, Robert and I have been improving the >>indexing as we can (placing all <indexterm> elements in the prolog), >>although there still are many holes. >> >>We *can* index during the forthcoming 30-day review, and I have several >>folks who have volunteered to work together under rigid guidelines to do >>so. >> >>Shall we move forward with this? I'm old school; I firmly believe that >>an index is an important and necessary entry point to information, and I >>don't think that online search can replace it. >> >>Let's talk about this. I know that we have TC members who think that an >>index is unprofessional in PDF output unless the <indexterm> entries are >>placed in-text. >> >>-- >>Best, >>Kris >> >>Kristen James Eberlein >>Chair, OASIS DITA Technical Committee >>Principal consultant, Eberlein Consulting >>www.eberleinconsulting.com < http://www.eberleinconsulting.com > >>+1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >> >> >>--------------------------------------------------------------------- >>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 >> >> > > > >--------------------------------------------------------------------- >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 > > > > > > > > > > >-- >Bob Thomas >+1 720 201 8260 >Skype: bob.thomas.colorado >Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype >Time zone: Mountain (GMT-7) > > > > > > > >

Here's a proposed heuristic that I think might get close to everyone's intuition here:   An <indexterm> should occur inline if and only if the location to which the reader is directed from the index will occur under a bolded (sub)heading that is NOT the topic title. In that case the indexterm should appear at the location of the nearest bolded subheading.   I arrived at this idea after pondering Eliot's remark about users not understanding/caring about incorrect page numbers. My thought is that the reader will be tolerant enough to accept a jump to the nearest "title" (section/topic/whatever) and scan the text from there. It's not until you (the reader's) eye hits another bolded title-like item that you wonder what the heck is wrong.   mag     From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Hudson, Scott Sent: Tuesday, July 07, 2015 11:59 AM To: Bob Thomas; Eliot Kimber Cc: DITA TC Subject: Re: [dita] Index in the PDF version of the spec?   I think it is useful to provide a quality index for the specification. As such, I also agree with Bob below. I think prolog indexterms should apply to the entire scope of the topic, while inlines should also be used when necessary. Since a lot of the spec has been broken into smaller components, I also hope it is true that we should be able to stick with the prolog approach in general. I do not want to rule out using the inline terms, though.   Thanks and best regards,   Scott Hudson Senior Consultant Comtech Services Inc. 303-232-7586   From: < dita@lists.oasis-open.org > on behalf of Bob Thomas Date: Tuesday, July 7, 2015 at 8:31 AM To: Eliot Kimber Cc: DITA TC Subject: Re: [dita] Index in the PDF version of the spec?   An index can be one of the better ways of finding things without having to take a drink out of the firehose that is search.   I agree with Eliot's position on inline vs. prolog. The only index terms in the prolog should be those that correspond with the entire scope of the topic. In general (i.e., not just the spec), writing shorter tightly scoped topics increases the likelihood that index terms will be in the prolog rather than inline.   Best Regards, Bob   On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber < ekimber@contrext.com > wrote: I agree that an index is important. But I also feel very strongly that if the index entries are not in line, the index should not be produced in PDF, for the simple reason that it will result in many page number references that are wrong (because they will point to the start of the topic rather than the place where the term actually occurs). Readers will not understand or care why the page number references are wrong and will assume that either we did poor job of indexing or assume that DITA's normal PDF production tools can't do indexing properly, neither of which is the case. So while having an index is important, if we can't put the index entries in the source at the point of occurrence of the terms indexed then we should not produce the index for PDF. I know from painful experience how much work it is to put index entries inline if you aren't doing it as you write. Cheers, Eliot ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com > wrote: >Background: > >We removed the index from the 1.2 specification because it was of >extremely low quality. Since then, Robert and I have been improving the >indexing as we can (placing all <indexterm> elements in the prolog), >although there still are many holes. > >We *can* index during the forthcoming 30-day review, and I have several >folks who have volunteered to work together under rigid guidelines to do >so. > >Shall we move forward with this? I'm old school; I firmly believe that >an index is an important and necessary entry point to information, and I >don't think that online search can replace it. > >Let's talk about this. I know that we have TC members who think that an >index is unprofessional in PDF output unless the <indexterm> entries are >placed in-text. > >-- >Best, >Kris > >Kristen James Eberlein >Chair, OASIS DITA Technical Committee >Principal consultant, Eberlein Consulting > www.eberleinconsulting.com > +1 919 682-2290 ; kriseberlein (skype) > > >--------------------------------------------------------------------- >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 > > --------------------------------------------------------------------- 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   -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)  

I don't agree with this heuristic. I hate to be difficult about this, but our audience is by and large technical communicators, people who have specific knowledge of and expectations for indexes. Thus they are likely to be the most critical audience possible, short of the members of the International Brotherhood of Professional Indexers. If the page number reference does not take you to the page where the thing indexed occurs they will notice and wonder why *and blame DITA for the failure*. Not the indexers, not the PDF generation process, not the Open Toolkit, DITA. That's my concern. We already have a huge problem in the community with statements like "DITA produces crappy print output". Having the DITA governing body produce a print document with what appear to be bad indexing would only exacerbate the problem. Cheers, E. ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/7/15, 2:13 PM, "Tom Magliery" <dita@lists.oasis-open.org on behalf of tom.magliery@justsystems.com> wrote: >Here's a proposed heuristic that I think might get close to everyone's >intuition here: > >An <indexterm> should occur inline if and only if the location to which >the reader is directed from the index will occur under a bolded >(sub)heading that is NOT the topic title. In that case the indexterm >should appear at the location of the nearest bolded subheading. > >I arrived at this idea after pondering Eliot's remark about users not >understanding/caring about incorrect page numbers. My thought is that the >reader will be tolerant enough to accept a jump to the nearest "title" >(section/topic/whatever) and scan the text from there. It's not until you >(the reader's) eye hits another bolded title-like item that you wonder >what the heck is wrong. > >mag > > >From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On >Behalf Of Hudson, Scott >Sent: Tuesday, July 07, 2015 11:59 AM >To: Bob Thomas; Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >I think it is useful to provide a quality index for the specification. As >such, I also agree with Bob below. I think prolog indexterms should apply >to the entire scope of the topic, while inlines should also be used when >necessary. Since a lot of the spec has been broken into smaller >components, I also hope it is true that we should be able to stick with >the prolog approach in general. I do not want to rule out using the >inline terms, though. > > > >Thanks and best regards, > > > >Scott Hudson > >Senior Consultant > >Comtech Services Inc. > >303-232-7586 > > > > > > > > >From: <dita@lists.oasis-open.org> on behalf of Bob Thomas >Date: Tuesday, July 7, 2015 at 8:31 AM >To: Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >An index can be one of the better ways of finding things without having >to take a drink out of the firehose that is search. > > >I agree with Eliot's position on inline vs. prolog. The only index terms >in the prolog should be those that correspond with the entire scope of >the topic. In general (i.e., not just the spec), writing shorter tightly >scoped topics increases the likelihood that index terms will be in the >prolog rather than inline. > > > >Best Regards, > >Bob > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber <ekimber@contrext.com> wrote: >I agree that an index is important. > >But I also feel very strongly that if the index entries are not in line, >the index should not be produced in PDF, for the simple reason that it >will result in many page number references that are wrong (because they >will point to the start of the topic rather than the place where the term >actually occurs). > >Readers will not understand or care why the page number references are >wrong and will assume that either we did poor job of indexing or assume >that DITA's normal PDF production tools can't do indexing properly, >neither of which is the case. > >So while having an index is important, if we can't put the index entries >in the source at the point of occurrence of the terms indexed then we >should not produce the index for PDF. > >I know from painful experience how much work it is to put index entries >inline if you aren't doing it as you write. > >Cheers, > >Eliot >---- >Eliot Kimber, Owner >Contrext, LLC > http://contrext.com > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" <dita@lists.oasis-open.org on >behalf of kris@eberleinconsulting.com> wrote: > >>Background: >> >>We removed the index from the 1.2 specification because it was of >>extremely low quality. Since then, Robert and I have been improving the >>indexing as we can (placing all <indexterm> elements in the prolog), >>although there still are many holes. >> >>We *can* index during the forthcoming 30-day review, and I have several >>folks who have volunteered to work together under rigid guidelines to do >>so. >> >>Shall we move forward with this? I'm old school; I firmly believe that >>an index is an important and necessary entry point to information, and I >>don't think that online search can replace it. >> >>Let's talk about this. I know that we have TC members who think that an >>index is unprofessional in PDF output unless the <indexterm> entries are >>placed in-text. >> >>-- >>Best, >>Kris >> >>Kristen James Eberlein >>Chair, OASIS DITA Technical Committee >>Principal consultant, Eberlein Consulting >>www.eberleinconsulting.com < http://www.eberleinconsulting.com > >>+1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >> >> >>--------------------------------------------------------------------- >>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 >> >> > > > >--------------------------------------------------------------------- >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 > > > > > > > > >-- >Bob Thomas >+1 720 201 8260 > >Skype: bob.thomas.colorado > >Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype > >Time zone: Mountain (GMT-7) > >

Shouldn't an indexterm in the prolog be treated as an index range across the entire topic when it is rendered? If not, then it sounds like something in the processing that should be adjusted? -—Scott On 7/8/15, 7:48 AM, "Eliot Kimber" <ekimber@contrext.com> wrote: >I don't agree with this heuristic. > >I hate to be difficult about this, but our audience is by and large >technical communicators, people who have specific knowledge of and >expectations for indexes. Thus they are likely to be the most critical >audience possible, short of the members of the International Brotherhood >of Professional Indexers. > >If the page number reference does not take you to the page where the thing >indexed occurs they will notice and wonder why *and blame DITA for the >failure*. Not the indexers, not the PDF generation process, not the Open >Toolkit, DITA. > >That's my concern. > >We already have a huge problem in the community with statements like "DITA >produces crappy print output". Having the DITA governing body produce a >print document with what appear to be bad indexing would only exacerbate >the problem. > >Cheers, > >E. > > >---- >Eliot Kimber, Owner >Contrext, LLC > http://contrext.com > > > > >On 7/7/15, 2:13 PM, "Tom Magliery" <dita@lists.oasis-open.org on behalf of >tom.magliery@justsystems.com> wrote: > >>Here's a proposed heuristic that I think might get close to everyone's >>intuition here: >> >>An <indexterm> should occur inline if and only if the location to which >>the reader is directed from the index will occur under a bolded >>(sub)heading that is NOT the topic title. In that case the indexterm >>should appear at the location of the nearest bolded subheading. >> >>I arrived at this idea after pondering Eliot's remark about users not >>understanding/caring about incorrect page numbers. My thought is that the >>reader will be tolerant enough to accept a jump to the nearest "title" >>(section/topic/whatever) and scan the text from there. It's not until you >>(the reader's) eye hits another bolded title-like item that you wonder >>what the heck is wrong. >> >>mag >> >> >>From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On >>Behalf Of Hudson, Scott >>Sent: Tuesday, July 07, 2015 11:59 AM >>To: Bob Thomas; Eliot Kimber >>Cc: DITA TC >>Subject: Re: [dita] Index in the PDF version of the spec? >> >> >> >>I think it is useful to provide a quality index for the specification. As >>such, I also agree with Bob below. I think prolog indexterms should apply >>to the entire scope of the topic, while inlines should also be used when >>necessary. Since a lot of the spec has been broken into smaller >>components, I also hope it is true that we should be able to stick with >>the prolog approach in general. I do not want to rule out using the >>inline terms, though. >> >> >> >>Thanks and best regards, >> >> >> >>Scott Hudson >> >>Senior Consultant >> >>Comtech Services Inc. >> >>303-232-7586 >> >> >> >> >> >> >> >> >>From: <dita@lists.oasis-open.org> on behalf of Bob Thomas >>Date: Tuesday, July 7, 2015 at 8:31 AM >>To: Eliot Kimber >>Cc: DITA TC >>Subject: Re: [dita] Index in the PDF version of the spec? >> >> >> >>An index can be one of the better ways of finding things without having >>to take a drink out of the firehose that is search. >> >> >>I agree with Eliot's position on inline vs. prolog. The only index terms >>in the prolog should be those that correspond with the entire scope of >>the topic. In general (i.e., not just the spec), writing shorter tightly >>scoped topics increases the likelihood that index terms will be in the >>prolog rather than inline. >> >> >> >>Best Regards, >> >>Bob >> >> >> >>On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber <ekimber@contrext.com> wrote: >>I agree that an index is important. >> >>But I also feel very strongly that if the index entries are not in line, >>the index should not be produced in PDF, for the simple reason that it >>will result in many page number references that are wrong (because they >>will point to the start of the topic rather than the place where the term >>actually occurs). >> >>Readers will not understand or care why the page number references are >>wrong and will assume that either we did poor job of indexing or assume >>that DITA's normal PDF production tools can't do indexing properly, >>neither of which is the case. >> >>So while having an index is important, if we can't put the index entries >>in the source at the point of occurrence of the terms indexed then we >>should not produce the index for PDF. >> >>I know from painful experience how much work it is to put index entries >>inline if you aren't doing it as you write. >> >>Cheers, >> >>Eliot >>---- >>Eliot Kimber, Owner >>Contrext, LLC >> http://contrext.com >> >> >> >> >>On 7/7/15, 9:00 AM, "Kristen James Eberlein" <dita@lists.oasis-open.org on >>behalf of kris@eberleinconsulting.com> wrote: >> >>>Background: >>> >>>We removed the index from the 1.2 specification because it was of >>>extremely low quality. Since then, Robert and I have been improving the >>>indexing as we can (placing all <indexterm> elements in the prolog), >>>although there still are many holes. >>> >>>We *can* index during the forthcoming 30-day review, and I have several >>>folks who have volunteered to work together under rigid guidelines to do >>>so. >>> >>>Shall we move forward with this? I'm old school; I firmly believe that >>>an index is an important and necessary entry point to information, and I >>>don't think that online search can replace it. >>> >>>Let's talk about this. I know that we have TC members who think that an >>>index is unprofessional in PDF output unless the <indexterm> entries are >>>placed in-text. >>> >>>-- >>>Best, >>>Kris >>> >>>Kristen James Eberlein >>>Chair, OASIS DITA Technical Committee >>>Principal consultant, Eberlein Consulting >>>www.eberleinconsulting.com < http://www.eberleinconsulting.com > >>>+1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >>> >>> >>>--------------------------------------------------------------------- >>>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 >>> >>> >> >> >> >>--------------------------------------------------------------------- >>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 >> >> >> >> >> >> >> >> >>-- >>Bob Thomas >>+1 720 201 8260 >> >>Skype: bob.thomas.colorado >> >>Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype >> >>Time zone: Mountain (GMT-7) >> >> > >

Definitely could provide a range of pages although it¹s better not to. JoAnn JoAnn T. Hackos, PhD President Comtech Services Inc. 710 Kipling Street, Suite 400 Denver, CO 80215 Joann.hackos@comtech-serv.com 303-232-7586 We will be hosting the CIDM Online Conference on July 29, 2015 More information is available: https://forum.infomanagementcenter.com < https://forum.infomanagementcenter.com/ > On 7/8/15, 8:07 AM, "Hudson, Scott" <scott.hudson@comtech-serv.com> wrote: >Shouldn't an indexterm in the prolog be treated as an index range across >the entire topic when it is rendered? If not, then it sounds like >something in the processing that should be adjusted? > >-‹Scott > > > >On 7/8/15, 7:48 AM, "Eliot Kimber" <ekimber@contrext.com> wrote: > >>I don't agree with this heuristic. >> >>I hate to be difficult about this, but our audience is by and large >>technical communicators, people who have specific knowledge of and >>expectations for indexes. Thus they are likely to be the most critical >>audience possible, short of the members of the International Brotherhood >>of Professional Indexers. >> >>If the page number reference does not take you to the page where the >>thing >>indexed occurs they will notice and wonder why *and blame DITA for the >>failure*. Not the indexers, not the PDF generation process, not the Open >>Toolkit, DITA. >> >>That's my concern. >> >>We already have a huge problem in the community with statements like >>"DITA >>produces crappy print output". Having the DITA governing body produce a >>print document with what appear to be bad indexing would only exacerbate >>the problem. >> >>Cheers, >> >>E. >> >> >>---- >>Eliot Kimber, Owner >>Contrext, LLC >> http://contrext.com >> >> >> >> >>On 7/7/15, 2:13 PM, "Tom Magliery" <dita@lists.oasis-open.org on behalf >>of >>tom.magliery@justsystems.com> wrote: >> >>>Here's a proposed heuristic that I think might get close to everyone's >>>intuition here: >>> >>>An <indexterm> should occur inline if and only if the location to which >>>the reader is directed from the index will occur under a bolded >>>(sub)heading that is NOT the topic title. In that case the indexterm >>>should appear at the location of the nearest bolded subheading. >>> >>>I arrived at this idea after pondering Eliot's remark about users not >>>understanding/caring about incorrect page numbers. My thought is that >>>the >>>reader will be tolerant enough to accept a jump to the nearest "title" >>>(section/topic/whatever) and scan the text from there. It's not until >>>you >>>(the reader's) eye hits another bolded title-like item that you wonder >>>what the heck is wrong. >>> >>>mag >>> >>> >>>From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On >>>Behalf Of Hudson, Scott >>>Sent: Tuesday, July 07, 2015 11:59 AM >>>To: Bob Thomas; Eliot Kimber >>>Cc: DITA TC >>>Subject: Re: [dita] Index in the PDF version of the spec? >>> >>> >>> >>>I think it is useful to provide a quality index for the specification. >>>As >>>such, I also agree with Bob below. I think prolog indexterms should >>>apply >>>to the entire scope of the topic, while inlines should also be used when >>>necessary. Since a lot of the spec has been broken into smaller >>>components, I also hope it is true that we should be able to stick with >>>the prolog approach in general. I do not want to rule out using the >>>inline terms, though. >>> >>> >>> >>>Thanks and best regards, >>> >>> >>> >>>Scott Hudson >>> >>>Senior Consultant >>> >>>Comtech Services Inc. >>> >>>303-232-7586 >>> >>> >>> >>> >>> >>> >>> >>> >>>From: <dita@lists.oasis-open.org> on behalf of Bob Thomas >>>Date: Tuesday, July 7, 2015 at 8:31 AM >>>To: Eliot Kimber >>>Cc: DITA TC >>>Subject: Re: [dita] Index in the PDF version of the spec? >>> >>> >>> >>>An index can be one of the better ways of finding things without having >>>to take a drink out of the firehose that is search. >>> >>> >>>I agree with Eliot's position on inline vs. prolog. The only index terms >>>in the prolog should be those that correspond with the entire scope of >>>the topic. In general (i.e., not just the spec), writing shorter tightly >>>scoped topics increases the likelihood that index terms will be in the >>>prolog rather than inline. >>> >>> >>> >>>Best Regards, >>> >>>Bob >>> >>> >>> >>>On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber <ekimber@contrext.com> >>>wrote: >>>I agree that an index is important. >>> >>>But I also feel very strongly that if the index entries are not in line, >>>the index should not be produced in PDF, for the simple reason that it >>>will result in many page number references that are wrong (because they >>>will point to the start of the topic rather than the place where the >>>term >>>actually occurs). >>> >>>Readers will not understand or care why the page number references are >>>wrong and will assume that either we did poor job of indexing or assume >>>that DITA's normal PDF production tools can't do indexing properly, >>>neither of which is the case. >>> >>>So while having an index is important, if we can't put the index entries >>>in the source at the point of occurrence of the terms indexed then we >>>should not produce the index for PDF. >>> >>>I know from painful experience how much work it is to put index entries >>>inline if you aren't doing it as you write. >>> >>>Cheers, >>> >>>Eliot >>>---- >>>Eliot Kimber, Owner >>>Contrext, LLC >>> http://contrext.com >>> >>> >>> >>> >>>On 7/7/15, 9:00 AM, "Kristen James Eberlein" <dita@lists.oasis-open.org >>>on >>>behalf of kris@eberleinconsulting.com> wrote: >>> >>>>Background: >>>> >>>>We removed the index from the 1.2 specification because it was of >>>>extremely low quality. Since then, Robert and I have been improving the >>>>indexing as we can (placing all <indexterm> elements in the prolog), >>>>although there still are many holes. >>>> >>>>We *can* index during the forthcoming 30-day review, and I have several >>>>folks who have volunteered to work together under rigid guidelines to >>>>do >>>>so. >>>> >>>>Shall we move forward with this? I'm old school; I firmly believe that >>>>an index is an important and necessary entry point to information, and >>>>I >>>>don't think that online search can replace it. >>>> >>>>Let's talk about this. I know that we have TC members who think that an >>>>index is unprofessional in PDF output unless the <indexterm> entries >>>>are >>>>placed in-text. >>>> >>>>-- >>>>Best, >>>>Kris >>>> >>>>Kristen James Eberlein >>>>Chair, OASIS DITA Technical Committee >>>>Principal consultant, Eberlein Consulting >>>>www.eberleinconsulting.com < http://www.eberleinconsulting.com > >>>>+1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >>>> >>>> >>>>--------------------------------------------------------------------- >>>>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 >>>> >>>> >>> >>> >>> >>>--------------------------------------------------------------------- >>>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 >>> >>> >>> >>> >>> >>> >>> >>> >>>-- >>>Bob Thomas >>>+1 720 201 8260 >>> >>>Skype: bob.thomas.colorado >>> >>>Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype >>> >>>Time zone: Mountain (GMT-7) >>> >>> >> >>

> We already have a huge problem in the community with statements like "DITA > produces crappy print output". Having the DITA governing body produce a > print document with what appear to be bad indexing would only exacerbate > the problem. I don't understand the certainty that this method will produce a bad index. There seems to be a certainty that even placing *most* entries in the prolog, with exceptions as needed, will produce a bad index. From the indexing done so far - speaking here about the more recent efforts in the architectural spec, not the old entries that need to be cleaned up / removed - if the entries we've added to the prolog take a reader directly to the title of the topic, it will be clear that they have reached the topic they wanted. For example, if you follow the index term "controlled values", there are 5 topics you can go to. Four of them have "controlled value" in the title; the fifth is about subject schemes, where "controlled value" appears in both the short description and the following paragraph. There are clear exceptions where inline indexing will improve the result. Titled sections, as Tom mentioned and as I mentioend on the call yesterday, might be a common case. There may be others, such as definition list entries in a long <dl> of core concepts. But most of our topics now have a tight focus, where the concept we want to index is part of the title or short description, so placing those entries in the prolog seems to be the best practice. Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) <dita@lists.oasis-open.org> wrote on 07/08/2015 08:48:02: > From: Eliot Kimber <ekimber@contrext.com> > To: Tom Magliery <tom.magliery@justsystems.com>, "Hudson, Scott" > <scott.hudson@comtech-serv.com>, Bob Thomas <bob.thomas@tagsmiths.com> > Cc: DITA TC <dita@lists.oasis-open.org> > Date: 07/08/2015 08:48 > Subject: Re: [dita] Index in the PDF version of the spec? > Sent by: <dita@lists.oasis-open.org> > > I don't agree with this heuristic. > > I hate to be difficult about this, but our audience is by and large > technical communicators, people who have specific knowledge of and > expectations for indexes. Thus they are likely to be the most critical > audience possible, short of the members of the International Brotherhood > of Professional Indexers. > > If the page number reference does not take you to the page where the thing > indexed occurs they will notice and wonder why *and blame DITA for the > failure*. Not the indexers, not the PDF generation process, not the Open > Toolkit, DITA. > > That's my concern. > > We already have a huge problem in the community with statements like "DITA > produces crappy print output". Having the DITA governing body produce a > print document with what appear to be bad indexing would only exacerbate > the problem. > > Cheers, > > E. > > > ---- > Eliot Kimber, Owner > Contrext, LLC > http://contrext.com > > > > > On 7/7/15, 2:13 PM, "Tom Magliery" <dita@lists.oasis-open.org on behalf of > tom.magliery@justsystems.com> wrote: > > >Here's a proposed heuristic that I think might get close to everyone's > >intuition here: > > > >An <indexterm> should occur inline if and only if the location to which > >the reader is directed from the index will occur under a bolded > >(sub)heading that is NOT the topic title. In that case the indexterm > >should appear at the location of the nearest bolded subheading. > > > >I arrived at this idea after pondering Eliot's remark about users not > >understanding/caring about incorrect page numbers. My thought is that the > >reader will be tolerant enough to accept a jump to the nearest "title" > >(section/topic/whatever) and scan the text from there. It's not until you > >(the reader's) eye hits another bolded title-like item that you wonder > >what the heck is wrong. > > > >mag > > > > > >From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On > >Behalf Of Hudson, Scott > >Sent: Tuesday, July 07, 2015 11:59 AM > >To: Bob Thomas; Eliot Kimber > >Cc: DITA TC > >Subject: Re: [dita] Index in the PDF version of the spec? > > > > > > > >I think it is useful to provide a quality index for the specification. As > >such, I also agree with Bob below. I think prolog indexterms should apply > >to the entire scope of the topic, while inlines should also be used when > >necessary. Since a lot of the spec has been broken into smaller > >components, I also hope it is true that we should be able to stick with > >the prolog approach in general. I do not want to rule out using the > >inline terms, though. > > > > > > > >Thanks and best regards, > > > > > > > >Scott Hudson > > > >Senior Consultant > > > >Comtech Services Inc. > > > >303-232-7586 > > > > > > > > > > > > > > > > > >From: <dita@lists.oasis-open.org> on behalf of Bob Thomas > >Date: Tuesday, July 7, 2015 at 8:31 AM > >To: Eliot Kimber > >Cc: DITA TC > >Subject: Re: [dita] Index in the PDF version of the spec? > > > > > > > >An index can be one of the better ways of finding things without having > >to take a drink out of the firehose that is search. > > > > > >I agree with Eliot's position on inline vs. prolog. The only index terms > >in the prolog should be those that correspond with the entire scope of > >the topic. In general (i.e., not just the spec), writing shorter tightly > >scoped topics increases the likelihood that index terms will be in the > >prolog rather than inline. > > > > > > > >Best Regards, > > > >Bob > > > > > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber <ekimber@contrext.com> wrote: > >I agree that an index is important. > > > >But I also feel very strongly that if the index entries are not in line, > >the index should not be produced in PDF, for the simple reason that it > >will result in many page number references that are wrong (because they > >will point to the start of the topic rather than the place where the term > >actually occurs). > > > >Readers will not understand or care why the page number references are > >wrong and will assume that either we did poor job of indexing or assume > >that DITA's normal PDF production tools can't do indexing properly, > >neither of which is the case. > > > >So while having an index is important, if we can't put the index entries > >in the source at the point of occurrence of the terms indexed then we > >should not produce the index for PDF. > > > >I know from painful experience how much work it is to put index entries > >inline if you aren't doing it as you write. > > > >Cheers, > > > >Eliot > >---- > >Eliot Kimber, Owner > >Contrext, LLC > > http://contrext.com > > > > > > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" <dita@lists.oasis-open.org on > >behalf of kris@eberleinconsulting.com> wrote: > > > >>Background: > >> > >>We removed the index from the 1.2 specification because it was of > >>extremely low quality. Since then, Robert and I have been improving the > >>indexing as we can (placing all <indexterm> elements in the prolog), > >>although there still are many holes. > >> > >>We *can* index during the forthcoming 30-day review, and I have several > >>folks who have volunteered to work together under rigid guidelines to do > >>so. > >> > >>Shall we move forward with this? I'm old school; I firmly believe that > >>an index is an important and necessary entry point to information, and I > >>don't think that online search can replace it. > >> > >>Let's talk about this. I know that we have TC members who think that an > >>index is unprofessional in PDF output unless the <indexterm> entries are > >>placed in-text. > >> > >>-- > >>Best, > >>Kris > >> > >>Kristen James Eberlein > >>Chair, OASIS DITA Technical Committee > >>Principal consultant, Eberlein Consulting > >>www.eberleinconsulting.com < http://www.eberleinconsulting.com > > >>+1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) > >> > >> > >>--------------------------------------------------------------------- > >>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 > >> > >> > > > > > > > >--------------------------------------------------------------------- > >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 > > > > > > > > > > > > > > > > > >-- > >Bob Thomas > >+1 720 201 8260 > > > >Skype: bob.thomas.colorado > > > >Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype > > > >Time zone: Mountain (GMT-7) > > > > > > > > --------------------------------------------------------------------- > 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 >

It's the TC's decision. If it was me I would not depend on index entries in the prolog. I'm not going to belabor the point. I've raised my objections and I stand by my concern. Cheers, Eliot ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/8/15, 9:39 AM, "Robert D Anderson" <dita@lists.oasis-open.org on behalf of robander@us.ibm.com> wrote: >> We already have a huge problem in the community with statements like >>"DITA >> produces crappy print output". Having the DITA governing body produce a >> print document with what appear to be bad indexing would only exacerbate >> the problem. > >I don't understand the certainty that this method will produce a bad >index. There seems to be a certainty that even placing *most* entries in >the prolog, with exceptions as needed, will produce a bad index. > >From the indexing done so far - speaking here about the more recent >efforts in the architectural spec, not the old entries that need to be >cleaned up / removed - if the entries we've added to the prolog take a >reader directly to the title of the topic, it will be clear that they >have reached the topic they wanted. For example, if you follow the index >term "controlled values", there are 5 topics you can go to. Four of them >have "controlled value" in the title; the fifth is about subject schemes, >where "controlled value" appears in both the short description and the >following paragraph. > >There are clear exceptions where inline indexing will improve the result. >Titled sections, as Tom mentioned and as I mentioend on the call >yesterday, might be a common case. There may be others, such as >definition list entries in a long <dl> of core concepts. But most of our >topics now have a tight focus, where the concept we want to index is part >of the title or short description, so placing those entries in the prolog >seems to be the best practice. > >Robert D Anderson >IBM Authoring Tools Development >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) > ><dita@lists.oasis-open.org> wrote on 07/08/2015 08:48:02: > >> From: Eliot Kimber <ekimber@contrext.com> >> To: Tom Magliery <tom.magliery@justsystems.com>, "Hudson, Scott" >> <scott.hudson@comtech-serv.com>, Bob Thomas <bob.thomas@tagsmiths.com> >> Cc: DITA TC <dita@lists.oasis-open.org> >> Date: 07/08/2015 08:48 >> Subject: Re: [dita] Index in the PDF version of the spec? >> Sent by: <dita@lists.oasis-open.org> >> >> I don't agree with this heuristic. >> >> I hate to be difficult about this, but our audience is by and large >> technical communicators, people who have specific knowledge of and >> expectations for indexes. Thus they are likely to be the most critical >> audience possible, short of the members of the International Brotherhood >> of Professional Indexers. >> >> If the page number reference does not take you to the page where the >>thing >> indexed occurs they will notice and wonder why *and blame DITA for the >> failure*. Not the indexers, not the PDF generation process, not the Open >> Toolkit, DITA. >> >> That's my concern. >> >> We already have a huge problem in the community with statements like >>"DITA >> produces crappy print output". Having the DITA governing body produce a >> print document with what appear to be bad indexing would only exacerbate >> the problem. >> >> Cheers, >> >> E. >> >> >> ---- >> Eliot Kimber, Owner >> Contrext, LLC >> http://contrext.com >> >> >> >> >> On 7/7/15, 2:13 PM, "Tom Magliery" <dita@lists.oasis-open.org on behalf >>of >> tom.magliery@justsystems.com> wrote: >> >> >Here's a proposed heuristic that I think might get close to everyone's >> >intuition here: >> > >> >An <indexterm> should occur inline if and only if the location to which >> >the reader is directed from the index will occur under a bolded >> >(sub)heading that is NOT the topic title. In that case the indexterm >> >should appear at the location of the nearest bolded subheading. >> > >> >I arrived at this idea after pondering Eliot's remark about users not >> >understanding/caring about incorrect page numbers. My thought is that >>the >> >reader will be tolerant enough to accept a jump to the nearest "title" >> >(section/topic/whatever) and scan the text from there. It's not until >>you >> >(the reader's) eye hits another bolded title-like item that you wonder >> >what the heck is wrong. >> > >> >mag >> > >> > >> >From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On >> >Behalf Of Hudson, Scott >> >Sent: Tuesday, July 07, 2015 11:59 AM >> >To: Bob Thomas; Eliot Kimber >> >Cc: DITA TC >> >Subject: Re: [dita] Index in the PDF version of the spec? >> > >> > >> > >> >I think it is useful to provide a quality index for the specification. >>As >> >such, I also agree with Bob below. I think prolog indexterms should >>apply >> >to the entire scope of the topic, while inlines should also be used >>when >> >necessary. Since a lot of the spec has been broken into smaller >> >components, I also hope it is true that we should be able to stick with >> >the prolog approach in general. I do not want to rule out using the >> >inline terms, though. >> > >> > >> > >> >Thanks and best regards, >> > >> > >> > >> >Scott Hudson >> > >> >Senior Consultant >> > >> >Comtech Services Inc. >> > >> >303-232-7586 >> > >> > >> > >> > >> > >> > >> > >> > >> >From: <dita@lists.oasis-open.org> on behalf of Bob Thomas >> >Date: Tuesday, July 7, 2015 at 8:31 AM >> >To: Eliot Kimber >> >Cc: DITA TC >> >Subject: Re: [dita] Index in the PDF version of the spec? >> > >> > >> > >> >An index can be one of the better ways of finding things without having >> >to take a drink out of the firehose that is search. >> > >> > >> >I agree with Eliot's position on inline vs. prolog. The only index >>terms >> >in the prolog should be those that correspond with the entire scope of >> >the topic. In general (i.e., not just the spec), writing shorter >>tightly >> >scoped topics increases the likelihood that index terms will be in the >> >prolog rather than inline. >> > >> > >> > >> >Best Regards, >> > >> >Bob >> > >> > >> > >> >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber <ekimber@contrext.com> >>wrote: >> >I agree that an index is important. >> > >> >But I also feel very strongly that if the index entries are not in >>line, >> >the index should not be produced in PDF, for the simple reason that it >> >will result in many page number references that are wrong (because they >> >will point to the start of the topic rather than the place where the >>term >> >actually occurs). >> > >> >Readers will not understand or care why the page number references are >> >wrong and will assume that either we did poor job of indexing or assume >> >that DITA's normal PDF production tools can't do indexing properly, >> >neither of which is the case. >> > >> >So while having an index is important, if we can't put the index >>entries >> >in the source at the point of occurrence of the terms indexed then we >> >should not produce the index for PDF. >> > >> >I know from painful experience how much work it is to put index entries >> >inline if you aren't doing it as you write. >> > >> >Cheers, >> > >> >Eliot >> >---- >> >Eliot Kimber, Owner >> >Contrext, LLC >> > http://contrext.com >> > >> > >> > >> > >> >On 7/7/15, 9:00 AM, "Kristen James Eberlein" >><dita@lists.oasis-open.org on >> >behalf of kris@eberleinconsulting.com> wrote: >> > >> >>Background: >> >> >> >>We removed the index from the 1.2 specification because it was of >> >>extremely low quality. Since then, Robert and I have been improving >>the >> >>indexing as we can (placing all <indexterm> elements in the prolog), >> >>although there still are many holes. >> >> >> >>We *can* index during the forthcoming 30-day review, and I have >>several >> >>folks who have volunteered to work together under rigid guidelines to >>do >> >>so. >> >> >> >>Shall we move forward with this? I'm old school; I firmly believe that >> >>an index is an important and necessary entry point to information, >>and I >> >>don't think that online search can replace it. >> >> >> >>Let's talk about this. I know that we have TC members who think that >>an >> >>index is unprofessional in PDF output unless the <indexterm> entries >>are >> >>placed in-text. >> >> >> >>-- >> >>Best, >> >>Kris >> >> >> >>Kristen James Eberlein >> >>Chair, OASIS DITA Technical Committee >> >>Principal consultant, Eberlein Consulting >> >>www.eberleinconsulting.com < http://www.eberleinconsulting.com > >> >>+1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >> >> >> >> >> >>--------------------------------------------------------------------- >> >>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 >> >> >> >> >> > >> > >> > >> >--------------------------------------------------------------------- >> >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 >> > >> > >> > >> > >> > >> > >> > >> > >> >-- >> >Bob Thomas >> >+1 720 201 8260 >> > >> >Skype: bob.thomas.colorado >> > >> >Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype >> > >> >Time zone: Mountain (GMT-7) >> > >> > >> >> >> >> --------------------------------------------------------------------- >> 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 >> >

I also insist that fidelity between index-referenced content and page numbers is essential. Beyond that, I argue in this message that 1) prolog is the only appropriate place for index terms that pertain to an entire topic, and 2) prolog is inappropriate for index terms that do not pertain to the entire topic. First, I believe that prolog/keywords/indexterm is the only appropriate place for index terms that pertain to an entire topic. Semantically, this makes sense because of the prolog element's position in the topic structure. But, let's consider the alternative. Suppose that we never use prolog for index terms and restrict ourselves to using only inline index markup. In this scenario, index terms that apply to the entire topic would presumably appear at the first opportunity in the topic structure (in Xpath, this would be /topic/body/*[1] or one of its descendants). Such markup violates the semantic intent of the vocabulary because the index term's containing element constitutes an implicit scope, and that scope won't usually match the topic scope. Now, back to page numbering. If you restrict prolog index terms to those that correspond to the topic scope, there is never a case where the index will display an incorrect page number for such terms. Second, if you place index terms in prolog that do not pertain to the entire topic, then you will likely have page numbers in the index that do not correspond to the content's location in the output. I agree with Eliot's assessment about our audience (this is also why I have been such a prig about wording during the review cycle). Consequently, I would rather not have an Index if the page numbering is going to be wrong upon occasion. Best Regards, Bob On Wed, Jul 8, 2015 at 7:48 AM, Eliot Kimber < ekimber@contrext.com > wrote: I don't agree with this heuristic. I hate to be difficult about this, but our audience is by and large technical communicators, people who have specific knowledge of and expectations for indexes. Thus they are likely to be the most critical audience possible, short of the members of the International Brotherhood of Professional Indexers. If the page number reference does not take you to the page where the thing indexed occurs they will notice and wonder why *and blame DITA for the failure*. Not the indexers, not the PDF generation process, not the Open Toolkit, DITA. That's my concern. We already have a huge problem in the community with statements like "DITA produces crappy print output". Having the DITA governing body produce a print document with what appear to be bad indexing would only exacerbate the problem. Cheers, E. ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/7/15, 2:13 PM, "Tom Magliery" < dita@lists.oasis-open.org on behalf of tom.magliery@justsystems.com > wrote: >Here's a proposed heuristic that I think might get close to everyone's >intuition here: > >An <indexterm> should occur inline if and only if the location to which >the reader is directed from the index will occur under a bolded >(sub)heading that is NOT the topic title. In that case the indexterm >should appear at the location of the nearest bolded subheading. > >I arrived at this idea after pondering Eliot's remark about users not >understanding/caring about incorrect page numbers. My thought is that the >reader will be tolerant enough to accept a jump to the nearest "title" >(section/topic/whatever) and scan the text from there. It's not until you >(the reader's) eye hits another bolded title-like item that you wonder >what the heck is wrong. > >mag > > >From: dita@lists.oasis-open.org [mailto: dita@lists.oasis-open.org ] On >Behalf Of Hudson, Scott >Sent: Tuesday, July 07, 2015 11:59 AM >To: Bob Thomas; Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >I think it is useful to provide a quality index for the specification. As >such, I also agree with Bob below. I think prolog indexterms should apply >to the entire scope of the topic, while inlines should also be used when >necessary. Since a lot of the spec has been broken into smaller >components, I also hope it is true that we should be able to stick with >the prolog approach in general. I do not want to rule out using the >inline terms, though. > > > >Thanks and best regards, > > > >Scott Hudson > >Senior Consultant > >Comtech Services Inc. > > 303-232-7586 > > > > > > > > >From: < dita@lists.oasis-open.org > on behalf of Bob Thomas >Date: Tuesday, July 7, 2015 at 8:31 AM >To: Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >An index can be one of the better ways of finding things without having >to take a drink out of the firehose that is search. > > >I agree with Eliot's position on inline vs. prolog. The only index terms >in the prolog should be those that correspond with the entire scope of >the topic. In general (i.e., not just the spec), writing shorter tightly >scoped topics increases the likelihood that index terms will be in the >prolog rather than inline. > > > >Best Regards, > >Bob > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber < ekimber@contrext.com > wrote: >I agree that an index is important. > >But I also feel very strongly that if the index entries are not in line, >the index should not be produced in PDF, for the simple reason that it >will result in many page number references that are wrong (because they >will point to the start of the topic rather than the place where the term >actually occurs). > >Readers will not understand or care why the page number references are >wrong and will assume that either we did poor job of indexing or assume >that DITA's normal PDF production tools can't do indexing properly, >neither of which is the case. > >So while having an index is important, if we can't put the index entries >in the source at the point of occurrence of the terms indexed then we >should not produce the index for PDF. > >I know from painful experience how much work it is to put index entries >inline if you aren't doing it as you write. > >Cheers, > >Eliot >---- >Eliot Kimber, Owner >Contrext, LLC > http://contrext.com > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on >behalf of kris@eberleinconsulting.com > wrote: > >>Background: >> >>We removed the index from the 1.2 specification because it was of >>extremely low quality. Since then, Robert and I have been improving the >>indexing as we can (placing all <indexterm> elements in the prolog), >>although there still are many holes. >> >>We *can* index during the forthcoming 30-day review, and I have several >>folks who have volunteered to work together under rigid guidelines to do >>so. >> >>Shall we move forward with this? I'm old school; I firmly believe that >>an index is an important and necessary entry point to information, and I >>don't think that online search can replace it. >> >>Let's talk about this. I know that we have TC members who think that an >>index is unprofessional in PDF output unless the <indexterm> entries are >>placed in-text. >> >>-- >>Best, >>Kris >> >>Kristen James Eberlein >>Chair, OASIS DITA Technical Committee >>Principal consultant, Eberlein Consulting >> www.eberleinconsulting.com < http://www.eberleinconsulting.com > >> +1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >> >> >>--------------------------------------------------------------------- >>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 >> >> > > > >--------------------------------------------------------------------- >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 > > > > > > > > >-- >Bob Thomas > +1 720 201 8260 > >Skype: bob.thomas.colorado > >Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > >Time zone: Mountain (GMT-7) > > -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

Hmm, I forgot about abstract and shortdesc in my rant about inline markup placement. On Wed, Jul 8, 2015 at 8:55 AM, Bob Thomas < bob.thomas@tagsmiths.com > wrote: I also insist that fidelity between index-referenced content and page numbers is essential. Beyond that, I argue in this message that 1) prolog is the only appropriate place for index terms that pertain to an entire topic, and 2) prolog is inappropriate for index terms that do not pertain to the entire topic. First, I believe that prolog/keywords/indexterm is the only appropriate place for index terms that pertain to an entire topic. Semantically, this makes sense because of the prolog element's position in the topic structure. But, let's consider the alternative. Suppose that we never use prolog for index terms and restrict ourselves to using only inline index markup. In this scenario, index terms that apply to the entire topic would presumably appear at the first opportunity in the topic structure (in Xpath, this would be /topic/body/*[1] or one of its descendants). Such markup violates the semantic intent of the vocabulary because the index term's containing element constitutes an implicit scope, and that scope won't usually match the topic scope. Now, back to page numbering. If you restrict prolog index terms to those that correspond to the topic scope, there is never a case where the index will display an incorrect page number for such terms. Second, if you place index terms in prolog that do not pertain to the entire topic, then you will likely have page numbers in the index that do not correspond to the content's location in the output. I agree with Eliot's assessment about our audience (this is also why I have been such a prig about wording during the review cycle). Consequently, I would rather not have an Index if the page numbering is going to be wrong upon occasion. Best Regards, Bob On Wed, Jul 8, 2015 at 7:48 AM, Eliot Kimber < ekimber@contrext.com > wrote: I don't agree with this heuristic. I hate to be difficult about this, but our audience is by and large technical communicators, people who have specific knowledge of and expectations for indexes. Thus they are likely to be the most critical audience possible, short of the members of the International Brotherhood of Professional Indexers. If the page number reference does not take you to the page where the thing indexed occurs they will notice and wonder why *and blame DITA for the failure*. Not the indexers, not the PDF generation process, not the Open Toolkit, DITA. That's my concern. We already have a huge problem in the community with statements like "DITA produces crappy print output". Having the DITA governing body produce a print document with what appear to be bad indexing would only exacerbate the problem. Cheers, E. ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/7/15, 2:13 PM, "Tom Magliery" < dita@lists.oasis-open.org on behalf of tom.magliery@justsystems.com > wrote: >Here's a proposed heuristic that I think might get close to everyone's >intuition here: > >An <indexterm> should occur inline if and only if the location to which >the reader is directed from the index will occur under a bolded >(sub)heading that is NOT the topic title. In that case the indexterm >should appear at the location of the nearest bolded subheading. > >I arrived at this idea after pondering Eliot's remark about users not >understanding/caring about incorrect page numbers. My thought is that the >reader will be tolerant enough to accept a jump to the nearest "title" >(section/topic/whatever) and scan the text from there. It's not until you >(the reader's) eye hits another bolded title-like item that you wonder >what the heck is wrong. > >mag > > >From: dita@lists.oasis-open.org [mailto: dita@lists.oasis-open.org ] On >Behalf Of Hudson, Scott >Sent: Tuesday, July 07, 2015 11:59 AM >To: Bob Thomas; Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >I think it is useful to provide a quality index for the specification. As >such, I also agree with Bob below. I think prolog indexterms should apply >to the entire scope of the topic, while inlines should also be used when >necessary. Since a lot of the spec has been broken into smaller >components, I also hope it is true that we should be able to stick with >the prolog approach in general. I do not want to rule out using the >inline terms, though. > > > >Thanks and best regards, > > > >Scott Hudson > >Senior Consultant > >Comtech Services Inc. > > 303-232-7586 > > > > > > > > >From: < dita@lists.oasis-open.org > on behalf of Bob Thomas >Date: Tuesday, July 7, 2015 at 8:31 AM >To: Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >An index can be one of the better ways of finding things without having >to take a drink out of the firehose that is search. > > >I agree with Eliot's position on inline vs. prolog. The only index terms >in the prolog should be those that correspond with the entire scope of >the topic. In general (i.e., not just the spec), writing shorter tightly >scoped topics increases the likelihood that index terms will be in the >prolog rather than inline. > > > >Best Regards, > >Bob > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber < ekimber@contrext.com > wrote: >I agree that an index is important. > >But I also feel very strongly that if the index entries are not in line, >the index should not be produced in PDF, for the simple reason that it >will result in many page number references that are wrong (because they >will point to the start of the topic rather than the place where the term >actually occurs). > >Readers will not understand or care why the page number references are >wrong and will assume that either we did poor job of indexing or assume >that DITA's normal PDF production tools can't do indexing properly, >neither of which is the case. > >So while having an index is important, if we can't put the index entries >in the source at the point of occurrence of the terms indexed then we >should not produce the index for PDF. > >I know from painful experience how much work it is to put index entries >inline if you aren't doing it as you write. > >Cheers, > >Eliot >---- >Eliot Kimber, Owner >Contrext, LLC > http://contrext.com > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on >behalf of kris@eberleinconsulting.com > wrote: > >>Background: >> >>We removed the index from the 1.2 specification because it was of >>extremely low quality. Since then, Robert and I have been improving the >>indexing as we can (placing all <indexterm> elements in the prolog), >>although there still are many holes. >> >>We *can* index during the forthcoming 30-day review, and I have several >>folks who have volunteered to work together under rigid guidelines to do >>so. >> >>Shall we move forward with this? I'm old school; I firmly believe that >>an index is an important and necessary entry point to information, and I >>don't think that online search can replace it. >> >>Let's talk about this. I know that we have TC members who think that an >>index is unprofessional in PDF output unless the <indexterm> entries are >>placed in-text. >> >>-- >>Best, >>Kris >> >>Kristen James Eberlein >>Chair, OASIS DITA Technical Committee >>Principal consultant, Eberlein Consulting >> www.eberleinconsulting.com < http://www.eberleinconsulting.com > >> +1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >> >> >>--------------------------------------------------------------------- >>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 >> >> > > > >--------------------------------------------------------------------- >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 > > > > > > > > >-- >Bob Thomas > +1 720 201 8260 > >Skype: bob.thomas.colorado > >Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > >Time zone: Mountain (GMT-7) > > -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

Earlier I said: "Now, back to page numbering. If you restrict prolog index terms to those that correspond to the topic scope, there is never a case where the index will display an incorrect page number for such terms." I withdraw this claim. Here is why. Suppose you have a topic that covers branch filtering. The index term "conditional processing" would apply to the entire topic. However, the text in the topic does not mention conditional processing by name until the last half of the topic. We are still logically correct in associating the "conditional processing" with the topic, but the reader knows nothing about our notions of scope, and   when the first mention of "conditional processing" falls a page other than where the topic began  the reader perceives that we are incompetent. This is essentially the same thing that Eliot said earlier, but I was too anchored to the notion of using indexterm in prolog to understand it. I can think of three choices: 1) no index, 2) add the @start attribute to all leaf-node indexterms in the prolog, 3) abandon prolog/keywords/indexterm entirely and use inline markup only. Best Regards, Bob On Wed, Jul 8, 2015 at 8:55 AM, Bob Thomas < bob.thomas@tagsmiths.com > wrote: I also insist that fidelity between index-referenced content and page numbers is essential. Beyond that, I argue in this message that 1) prolog is the only appropriate place for index terms that pertain to an entire topic, and 2) prolog is inappropriate for index terms that do not pertain to the entire topic. First, I believe that prolog/keywords/indexterm is the only appropriate place for index terms that pertain to an entire topic. Semantically, this makes sense because of the prolog element's position in the topic structure. But, let's consider the alternative. Suppose that we never use prolog for index terms and restrict ourselves to using only inline index markup. In this scenario, index terms that apply to the entire topic would presumably appear at the first opportunity in the topic structure (in Xpath, this would be /topic/body/*[1] or one of its descendants). Such markup violates the semantic intent of the vocabulary because the index term's containing element constitutes an implicit scope, and that scope won't usually match the topic scope. Now, back to page numbering. If you restrict prolog index terms to those that correspond to the topic scope, there is never a case where the index will display an incorrect page number for such terms. Second, if you place index terms in prolog that do not pertain to the entire topic, then you will likely have page numbers in the index that do not correspond to the content's location in the output. I agree with Eliot's assessment about our audience (this is also why I have been such a prig about wording during the review cycle). Consequently, I would rather not have an Index if the page numbering is going to be wrong upon occasion. Best Regards, Bob On Wed, Jul 8, 2015 at 7:48 AM, Eliot Kimber < ekimber@contrext.com > wrote: I don't agree with this heuristic. I hate to be difficult about this, but our audience is by and large technical communicators, people who have specific knowledge of and expectations for indexes. Thus they are likely to be the most critical audience possible, short of the members of the International Brotherhood of Professional Indexers. If the page number reference does not take you to the page where the thing indexed occurs they will notice and wonder why *and blame DITA for the failure*. Not the indexers, not the PDF generation process, not the Open Toolkit, DITA. That's my concern. We already have a huge problem in the community with statements like "DITA produces crappy print output". Having the DITA governing body produce a print document with what appear to be bad indexing would only exacerbate the problem. Cheers, E. ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/7/15, 2:13 PM, "Tom Magliery" < dita@lists.oasis-open.org on behalf of tom.magliery@justsystems.com > wrote: >Here's a proposed heuristic that I think might get close to everyone's >intuition here: > >An <indexterm> should occur inline if and only if the location to which >the reader is directed from the index will occur under a bolded >(sub)heading that is NOT the topic title. In that case the indexterm >should appear at the location of the nearest bolded subheading. > >I arrived at this idea after pondering Eliot's remark about users not >understanding/caring about incorrect page numbers. My thought is that the >reader will be tolerant enough to accept a jump to the nearest "title" >(section/topic/whatever) and scan the text from there. It's not until you >(the reader's) eye hits another bolded title-like item that you wonder >what the heck is wrong. > >mag > > >From: dita@lists.oasis-open.org [mailto: dita@lists.oasis-open.org ] On >Behalf Of Hudson, Scott >Sent: Tuesday, July 07, 2015 11:59 AM >To: Bob Thomas; Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >I think it is useful to provide a quality index for the specification. As >such, I also agree with Bob below. I think prolog indexterms should apply >to the entire scope of the topic, while inlines should also be used when >necessary. Since a lot of the spec has been broken into smaller >components, I also hope it is true that we should be able to stick with >the prolog approach in general. I do not want to rule out using the >inline terms, though. > > > >Thanks and best regards, > > > >Scott Hudson > >Senior Consultant > >Comtech Services Inc. > > 303-232-7586 > > > > > > > > >From: < dita@lists.oasis-open.org > on behalf of Bob Thomas >Date: Tuesday, July 7, 2015 at 8:31 AM >To: Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >An index can be one of the better ways of finding things without having >to take a drink out of the firehose that is search. > > >I agree with Eliot's position on inline vs. prolog. The only index terms >in the prolog should be those that correspond with the entire scope of >the topic. In general (i.e., not just the spec), writing shorter tightly >scoped topics increases the likelihood that index terms will be in the >prolog rather than inline. > > > >Best Regards, > >Bob > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber < ekimber@contrext.com > wrote: >I agree that an index is important. > >But I also feel very strongly that if the index entries are not in line, >the index should not be produced in PDF, for the simple reason that it >will result in many page number references that are wrong (because they >will point to the start of the topic rather than the place where the term >actually occurs). > >Readers will not understand or care why the page number references are >wrong and will assume that either we did poor job of indexing or assume >that DITA's normal PDF production tools can't do indexing properly, >neither of which is the case. > >So while having an index is important, if we can't put the index entries >in the source at the point of occurrence of the terms indexed then we >should not produce the index for PDF. > >I know from painful experience how much work it is to put index entries >inline if you aren't doing it as you write. > >Cheers, > >Eliot >---- >Eliot Kimber, Owner >Contrext, LLC > http://contrext.com > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on >behalf of kris@eberleinconsulting.com > wrote: > >>Background: >> >>We removed the index from the 1.2 specification because it was of >>extremely low quality. Since then, Robert and I have been improving the >>indexing as we can (placing all <indexterm> elements in the prolog), >>although there still are many holes. >> >>We *can* index during the forthcoming 30-day review, and I have several >>folks who have volunteered to work together under rigid guidelines to do >>so. >> >>Shall we move forward with this? I'm old school; I firmly believe that >>an index is an important and necessary entry point to information, and I >>don't think that online search can replace it. >> >>Let's talk about this. I know that we have TC members who think that an >>index is unprofessional in PDF output unless the <indexterm> entries are >>placed in-text. >> >>-- >>Best, >>Kris >> >>Kristen James Eberlein >>Chair, OASIS DITA Technical Committee >>Principal consultant, Eberlein Consulting >> www.eberleinconsulting.com < http://www.eberleinconsulting.com > >> +1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >> >> >>--------------------------------------------------------------------- >>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 >> >> > > > >--------------------------------------------------------------------- >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 > > > > > > > > >-- >Bob Thomas > +1 720 201 8260 > >Skype: bob.thomas.colorado > >Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > >Time zone: Mountain (GMT-7) > > -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

Do we have any actual cases where an index term refers to a subject that is not represented in a heading (topic level or section level)? Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Bob Thomas <bob.thomas@tagsmiths.com> To:         Eliot Kimber <ekimber@contrext.com> Cc:         Tom Magliery <tom.magliery@justsystems.com>, "Hudson, Scott" <scott.hudson@comtech-serv.com>, DITA TC <dita@lists.oasis-open.org> Date:         07/08/2015 01:04 PM Subject:         Re: [dita] Index in the PDF version of the spec? Sent by:         <dita@lists.oasis-open.org> Earlier I said: "Now, back to page numbering. If you restrict prolog index terms to those that correspond to the topic scope, there is never a case where the index will display an incorrect page number for such terms." I withdraw this claim. Here is why. Suppose you have a topic that covers branch filtering. The index term "conditional processing" would apply to the entire topic. However, the text in the topic does not mention conditional processing by name until the last half of the topic. We are still logically correct in associating the "conditional processing" with the topic, but the reader knows nothing about our notions of scope, and when the first mention of "conditional processing" falls a page other than where the topic began the reader perceives that we are incompetent. This is essentially the same thing that Eliot said earlier, but I was too anchored to the notion of using indexterm in prolog to understand it. I can think of three choices: 1) no index, 2) add the @start attribute to all leaf-node indexterms in the prolog, 3) abandon prolog/keywords/indexterm entirely and use inline markup only. Best Regards, Bob On Wed, Jul 8, 2015 at 8:55 AM, Bob Thomas < bob.thomas@tagsmiths.com > wrote: I also insist that fidelity between index-referenced content and page numbers is essential. Beyond that, I argue in this message that 1) prolog is the only appropriate place for index terms that pertain to an entire topic, and 2) prolog is inappropriate for index terms that do not pertain to the entire topic. First, I believe that prolog/keywords/indexterm is the only appropriate place for index terms that pertain to an entire topic. Semantically, this makes sense because of the prolog element's position in the topic structure. But, let's consider the alternative. Suppose that we never use prolog for index terms and restrict ourselves to using only inline index markup. In this scenario, index terms that apply to the entire topic would presumably appear at the first opportunity in the topic structure (in Xpath, this would be /topic/body/*[1] or one of its descendants). Such markup violates the semantic intent of the vocabulary because the index term's containing element constitutes an implicit scope, and that scope won't usually match the topic scope. Now, back to page numbering. If you restrict prolog index terms to those that correspond to the topic scope, there is never a case where the index will display an incorrect page number for such terms. Second, if you place index terms in prolog that do not pertain to the entire topic, then you will likely have page numbers in the index that do not correspond to the content's location in the output. I agree with Eliot's assessment about our audience (this is also why I have been such a prig about wording during the review cycle). Consequently, I would rather not have an Index if the page numbering is going to be wrong upon occasion. Best Regards, Bob On Wed, Jul 8, 2015 at 7:48 AM, Eliot Kimber < ekimber@contrext.com > wrote: I don't agree with this heuristic. I hate to be difficult about this, but our audience is by and large technical communicators, people who have specific knowledge of and expectations for indexes. Thus they are likely to be the most critical audience possible, short of the members of the International Brotherhood of Professional Indexers. If the page number reference does not take you to the page where the thing indexed occurs they will notice and wonder why *and blame DITA for the failure*. Not the indexers, not the PDF generation process, not the Open Toolkit, DITA. That's my concern. We already have a huge problem in the community with statements like "DITA produces crappy print output". Having the DITA governing body produce a print document with what appear to be bad indexing would only exacerbate the problem. Cheers, E. ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/7/15, 2:13 PM, "Tom Magliery" < dita@lists.oasis-open.org on behalf of tom.magliery@justsystems.com > wrote: >Here's a proposed heuristic that I think might get close to everyone's >intuition here: > >An <indexterm> should occur inline if and only if the location to which >the reader is directed from the index will occur under a bolded >(sub)heading that is NOT the topic title. In that case the indexterm >should appear at the location of the nearest bolded subheading. > >I arrived at this idea after pondering Eliot's remark about users not >understanding/caring about incorrect page numbers. My thought is that the >reader will be tolerant enough to accept a jump to the nearest "title" >(section/topic/whatever) and scan the text from there. It's not until you >(the reader's) eye hits another bolded title-like item that you wonder >what the heck is wrong. > >mag > > >From: dita@lists.oasis-open.org [mailto: dita@lists.oasis-open.org ] On >Behalf Of Hudson, Scott >Sent: Tuesday, July 07, 2015 11:59 AM >To: Bob Thomas; Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >I think it is useful to provide a quality index for the specification. As >such, I also agree with Bob below. I think prolog indexterms should apply >to the entire scope of the topic, while inlines should also be used when >necessary. Since a lot of the spec has been broken into smaller >components, I also hope it is true that we should be able to stick with >the prolog approach in general. I do not want to rule out using the >inline terms, though. > > > >Thanks and best regards, > > > >Scott Hudson > >Senior Consultant > >Comtech Services Inc. > > 303-232-7586 > > > > > > > > >From: < dita@lists.oasis-open.org > on behalf of Bob Thomas >Date: Tuesday, July 7, 2015 at 8:31 AM >To: Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >An index can be one of the better ways of finding things without having >to take a drink out of the firehose that is search. > > >I agree with Eliot's position on inline vs. prolog. The only index terms >in the prolog should be those that correspond with the entire scope of >the topic. In general (i.e., not just the spec), writing shorter tightly >scoped topics increases the likelihood that index terms will be in the >prolog rather than inline. > > > >Best Regards, > >Bob > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber < ekimber@contrext.com > wrote: >I agree that an index is important. > >But I also feel very strongly that if the index entries are not in line, >the index should not be produced in PDF, for the simple reason that it >will result in many page number references that are wrong (because they >will point to the start of the topic rather than the place where the term >actually occurs). > >Readers will not understand or care why the page number references are >wrong and will assume that either we did poor job of indexing or assume >that DITA's normal PDF production tools can't do indexing properly, >neither of which is the case. > >So while having an index is important, if we can't put the index entries >in the source at the point of occurrence of the terms indexed then we >should not produce the index for PDF. > >I know from painful experience how much work it is to put index entries >inline if you aren't doing it as you write. > >Cheers, > >Eliot >---- >Eliot Kimber, Owner >Contrext, LLC > http://contrext.com > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on >behalf of kris@eberleinconsulting.com > wrote: > >>Background: >> >>We removed the index from the 1.2 specification because it was of >>extremely low quality. Since then, Robert and I have been improving the >>indexing as we can (placing all <indexterm> elements in the prolog), >>although there still are many holes. >> >>We *can* index during the forthcoming 30-day review, and I have several >>folks who have volunteered to work together under rigid guidelines to do >>so. >> >>Shall we move forward with this? I'm old school; I firmly believe that >>an index is an important and necessary entry point to information, and I >>don't think that online search can replace it. >> >>Let's talk about this. I know that we have TC members who think that an >>index is unprofessional in PDF output unless the <indexterm> entries are >>placed in-text. >> >>-- >>Best, >>Kris >> >>Kristen James Eberlein >>Chair, OASIS DITA Technical Committee >>Principal consultant, Eberlein Consulting >> www.eberleinconsulting.com < http://www.eberleinconsulting.com > >> +1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >> >> >>--------------------------------------------------------------------- >>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 >> >> > > > >--------------------------------------------------------------------- >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 > > > > > > > > >-- >Bob Thomas > +1 720 201 8260 > >Skype: bob.thomas.colorado > >Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > >Time zone: Mountain (GMT-7) > > -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

Let me ask a different question - would the following guidelines be acceptable? - if the topic title mentions the subject, put the index item in the prolog - if it doesn't, put the index item as close to the subject matter as possible Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Michael Priestley/Toronto/IBM@IBMCA To:         Bob Thomas <bob.thomas@tagsmiths.com> Cc:         Eliot Kimber <ekimber@contrext.com>, Tom Magliery <tom.magliery@justsystems.com>, "Hudson, Scott" <scott.hudson@comtech-serv.com>, DITA TC <dita@lists.oasis-open.org> Date:         07/08/2015 01:44 PM Subject:         Re: [dita] Index in the PDF version of the spec? Sent by:         <dita@lists.oasis-open.org> Do we have any actual cases where an index term refers to a subject that is not represented in a heading (topic level or section level)? Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Bob Thomas <bob.thomas@tagsmiths.com> To:         Eliot Kimber <ekimber@contrext.com> Cc:         Tom Magliery <tom.magliery@justsystems.com>, "Hudson, Scott" <scott.hudson@comtech-serv.com>, DITA TC <dita@lists.oasis-open.org> Date:         07/08/2015 01:04 PM Subject:         Re: [dita] Index in the PDF version of the spec? Sent by:         <dita@lists.oasis-open.org> Earlier I said: "Now, back to page numbering. If you restrict prolog index terms to those that correspond to the topic scope, there is never a case where the index will display an incorrect page number for such terms." I withdraw this claim. Here is why. Suppose you have a topic that covers branch filtering. The index term "conditional processing" would apply to the entire topic. However, the text in the topic does not mention conditional processing by name until the last half of the topic. We are still logically correct in associating the "conditional processing" with the topic, but the reader knows nothing about our notions of scope, and when the first mention of "conditional processing" falls a page other than where the topic began the reader perceives that we are incompetent. This is essentially the same thing that Eliot said earlier, but I was too anchored to the notion of using indexterm in prolog to understand it. I can think of three choices: 1) no index, 2) add the @start attribute to all leaf-node indexterms in the prolog, 3) abandon prolog/keywords/indexterm entirely and use inline markup only. Best Regards, Bob On Wed, Jul 8, 2015 at 8:55 AM, Bob Thomas < bob.thomas@tagsmiths.com > wrote: I also insist that fidelity between index-referenced content and page numbers is essential. Beyond that, I argue in this message that 1) prolog is the only appropriate place for index terms that pertain to an entire topic, and 2) prolog is inappropriate for index terms that do not pertain to the entire topic. First, I believe that prolog/keywords/indexterm is the only appropriate place for index terms that pertain to an entire topic. Semantically, this makes sense because of the prolog element's position in the topic structure. But, let's consider the alternative. Suppose that we never use prolog for index terms and restrict ourselves to using only inline index markup. In this scenario, index terms that apply to the entire topic would presumably appear at the first opportunity in the topic structure (in Xpath, this would be /topic/body/*[1] or one of its descendants). Such markup violates the semantic intent of the vocabulary because the index term's containing element constitutes an implicit scope, and that scope won't usually match the topic scope. Now, back to page numbering. If you restrict prolog index terms to those that correspond to the topic scope, there is never a case where the index will display an incorrect page number for such terms. Second, if you place index terms in prolog that do not pertain to the entire topic, then you will likely have page numbers in the index that do not correspond to the content's location in the output. I agree with Eliot's assessment about our audience (this is also why I have been such a prig about wording during the review cycle). Consequently, I would rather not have an Index if the page numbering is going to be wrong upon occasion. Best Regards, Bob On Wed, Jul 8, 2015 at 7:48 AM, Eliot Kimber < ekimber@contrext.com > wrote: I don't agree with this heuristic. I hate to be difficult about this, but our audience is by and large technical communicators, people who have specific knowledge of and expectations for indexes. Thus they are likely to be the most critical audience possible, short of the members of the International Brotherhood of Professional Indexers. If the page number reference does not take you to the page where the thing indexed occurs they will notice and wonder why *and blame DITA for the failure*. Not the indexers, not the PDF generation process, not the Open Toolkit, DITA. That's my concern. We already have a huge problem in the community with statements like "DITA produces crappy print output". Having the DITA governing body produce a print document with what appear to be bad indexing would only exacerbate the problem. Cheers, E. ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/7/15, 2:13 PM, "Tom Magliery" < dita@lists.oasis-open.org on behalf of tom.magliery@justsystems.com > wrote: >Here's a proposed heuristic that I think might get close to everyone's >intuition here: > >An <indexterm> should occur inline if and only if the location to which >the reader is directed from the index will occur under a bolded >(sub)heading that is NOT the topic title. In that case the indexterm >should appear at the location of the nearest bolded subheading. > >I arrived at this idea after pondering Eliot's remark about users not >understanding/caring about incorrect page numbers. My thought is that the >reader will be tolerant enough to accept a jump to the nearest "title" >(section/topic/whatever) and scan the text from there. It's not until you >(the reader's) eye hits another bolded title-like item that you wonder >what the heck is wrong. > >mag > > >From: dita@lists.oasis-open.org [mailto: dita@lists.oasis-open.org ] On >Behalf Of Hudson, Scott >Sent: Tuesday, July 07, 2015 11:59 AM >To: Bob Thomas; Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >I think it is useful to provide a quality index for the specification. As >such, I also agree with Bob below. I think prolog indexterms should apply >to the entire scope of the topic, while inlines should also be used when >necessary. Since a lot of the spec has been broken into smaller >components, I also hope it is true that we should be able to stick with >the prolog approach in general. I do not want to rule out using the >inline terms, though. > > > >Thanks and best regards, > > > >Scott Hudson > >Senior Consultant > >Comtech Services Inc. > > 303-232-7586 > > > > > > > > >From: < dita@lists.oasis-open.org > on behalf of Bob Thomas >Date: Tuesday, July 7, 2015 at 8:31 AM >To: Eliot Kimber >Cc: DITA TC >Subject: Re: [dita] Index in the PDF version of the spec? > > > >An index can be one of the better ways of finding things without having >to take a drink out of the firehose that is search. > > >I agree with Eliot's position on inline vs. prolog. The only index terms >in the prolog should be those that correspond with the entire scope of >the topic. In general (i.e., not just the spec), writing shorter tightly >scoped topics increases the likelihood that index terms will be in the >prolog rather than inline. > > > >Best Regards, > >Bob > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber < ekimber@contrext.com > wrote: >I agree that an index is important. > >But I also feel very strongly that if the index entries are not in line, >the index should not be produced in PDF, for the simple reason that it >will result in many page number references that are wrong (because they >will point to the start of the topic rather than the place where the term >actually occurs). > >Readers will not understand or care why the page number references are >wrong and will assume that either we did poor job of indexing or assume >that DITA's normal PDF production tools can't do indexing properly, >neither of which is the case. > >So while having an index is important, if we can't put the index entries >in the source at the point of occurrence of the terms indexed then we >should not produce the index for PDF. > >I know from painful experience how much work it is to put index entries >inline if you aren't doing it as you write. > >Cheers, > >Eliot >---- >Eliot Kimber, Owner >Contrext, LLC > http://contrext.com > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on >behalf of kris@eberleinconsulting.com > wrote: > >>Background: >> >>We removed the index from the 1.2 specification because it was of >>extremely low quality. Since then, Robert and I have been improving the >>indexing as we can (placing all <indexterm> elements in the prolog), >>although there still are many holes. >> >>We *can* index during the forthcoming 30-day review, and I have several >>folks who have volunteered to work together under rigid guidelines to do >>so. >> >>Shall we move forward with this? I'm old school; I firmly believe that >>an index is an important and necessary entry point to information, and I >>don't think that online search can replace it. >> >>Let's talk about this. I know that we have TC members who think that an >>index is unprofessional in PDF output unless the <indexterm> entries are >>placed in-text. >> >>-- >>Best, >>Kris >> >>Kristen James Eberlein >>Chair, OASIS DITA Technical Committee >>Principal consultant, Eberlein Consulting >> www.eberleinconsulting.com < http://www.eberleinconsulting.com > >> +1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >> >> >>--------------------------------------------------------------------- >>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 >> >> > > > >--------------------------------------------------------------------- >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 > > > > > > > > >-- >Bob Thomas > +1 720 201 8260 > >Skype: bob.thomas.colorado > >Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > >Time zone: Mountain (GMT-7) > > -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7) -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)

Caveat: I am not a member of the Brotherhood of Professional Indexers so my question/comment here may seem naive. > I can think of three choices: 1) no index, 2) add the @start > attribute to all leaf-node indexterms in the prolog, 3) abandon > prolog/keywords/indexterm entirely and use inline markup only. One of the index entries Kris added for "controlled values" currently takes me to the topic "Binding controlled values to an attribute". The title and first paragraphs are all clearly related to the subject. If I follow that index entry to that topic, and only find a title plus one paragraphs before the page ends, I'm not going to stop reading, regardless of whether the index itself linked to "page x" versus "page x to X+1". Are others likely to get annoyed because the index didn't warn ahead of time that the topic continued to a second page? Most (not all) of the topics we should index are short enough that they will appear on one or two pages. Implementing suggestion #2 for will mean the majority of our entries change from something like "123" to "123-124". Moving all index terms to the body (suggestion #3) would mean each index target appears only with the first paragraph, after the title and short description. There will be situations where the title and short description are on the previous page, meaning we're back in the "obviously bad" scenario of going to the wrong location. I started this note 90 minutes ago and now see one from Michael that makes sense to me. 2 simple rules, based on the content we find (rather than rules based on what we assume we will find). Quoting Michael, with one (addition): - if the topic title (or short description) mentions the subject, put the index item in the prolog - if it doesn't, put the index item as close to the subject matter as possible Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) <dita@lists.oasis-open.org> wrote on 07/08/2015 12:03:58: > From: Bob Thomas <bob.thomas@tagsmiths.com> > To: Eliot Kimber <ekimber@contrext.com> > Cc: Tom Magliery <tom.magliery@justsystems.com>, "Hudson, Scott" > <scott.hudson@comtech-serv.com>, DITA TC <dita@lists.oasis-open.org> > Date: 07/08/2015 12:04 > Subject: Re: [dita] Index in the PDF version of the spec? > Sent by: <dita@lists.oasis-open.org> > > Earlier I said: > > "Now, back to page numbering. If you restrict prolog index terms to > those that correspond to the topic scope, there is never a case > where the index will display an incorrect page number for such terms." > > I withdraw this claim. Here is why. Suppose you have a topic that > covers branch filtering. The index term "conditional processing" > would apply to the entire topic. However, the text in the topic does > not mention conditional processing by name until the last half of > the topic. We are still logically correct in associating the > "conditional processing" with the topic, but the reader knows > nothing about our notions of scope, and when the first mention of > "conditional processing" falls a page other than where the topic > began the reader perceives that we are incompetent. This is > essentially the same thing that Eliot said earlier, but I was too > anchored to the notion of using indexterm in prolog to understand it. > > I can think of three choices: 1) no index, 2) add the @start > attribute to all leaf-node indexterms in the prolog, 3) abandon > prolog/keywords/indexterm entirely and use inline markup only. > > Best Regards, > Bob > > On Wed, Jul 8, 2015 at 8:55 AM, Bob Thomas <bob.thomas@tagsmiths.com> wrote: > I also insist that fidelity between index-referenced content and > page numbers is essential. Beyond that, I argue in this message that > 1) prolog is the only appropriate place for index terms that pertain > to an entire topic, and 2) prolog is inappropriate for index terms > that do not pertain to the entire topic. > > First, I believe that prolog/keywords/indexterm is the only > appropriate place for index terms that pertain to an entire topic. > Semantically, this makes sense because of the prolog element's > position in the topic structure. But, let's consider the > alternative. Suppose that we never use prolog for index terms and > restrict ourselves to using only inline index markup. In this > scenario, index terms that apply to the entire topic would > presumably appear at the first opportunity in the topic structure > (in Xpath, this would be /topic/body/*[1] or one of its > descendants). Such markup violates the semantic intent of the > vocabulary because the index term's containing element constitutes > an implicit scope, and that scope won't usually match the topic scope. > > Now, back to page numbering. If you restrict prolog index terms to > those that correspond to the topic scope, there is never a case > where the index will display an incorrect page number for such terms. > > Second, if you place index terms in prolog that do not pertain to > the entire topic, then you will likely have page numbers in the > index that do not correspond to the content's location in the > output. I agree with Eliot's assessment about our audience (this is > also why I have been such a prig about wording during the review > cycle). Consequently, I would rather not have an Index if the page > numbering is going to be wrong upon occasion. > > Best Regards, > Bob > > On Wed, Jul 8, 2015 at 7:48 AM, Eliot Kimber <ekimber@contrext.com> wrote: > I don't agree with this heuristic. > > I hate to be difficult about this, but our audience is by and large > technical communicators, people who have specific knowledge of and > expectations for indexes. Thus they are likely to be the most critical > audience possible, short of the members of the International Brotherhood > of Professional Indexers. > > If the page number reference does not take you to the page where the thing > indexed occurs they will notice and wonder why *and blame DITA for the > failure*. Not the indexers, not the PDF generation process, not the Open > Toolkit, DITA. > > That's my concern. > > We already have a huge problem in the community with statements like "DITA > produces crappy print output". Having the DITA governing body produce a > print document with what appear to be bad indexing would only exacerbate > the problem. > > Cheers, > > E. > > > ---- > Eliot Kimber, Owner > Contrext, LLC > http://contrext.com > > > > > On 7/7/15, 2:13 PM, "Tom Magliery" <dita@lists.oasis-open.org on behalf of > tom.magliery@justsystems.com> wrote: > > >Here's a proposed heuristic that I think might get close to everyone's > >intuition here: > > > >An <indexterm> should occur inline if and only if the location to which > >the reader is directed from the index will occur under a bolded > >(sub)heading that is NOT the topic title. In that case the indexterm > >should appear at the location of the nearest bolded subheading. > > > >I arrived at this idea after pondering Eliot's remark about users not > >understanding/caring about incorrect page numbers. My thought is that the > >reader will be tolerant enough to accept a jump to the nearest "title" > >(section/topic/whatever) and scan the text from there. It's not until you > >(the reader's) eye hits another bolded title-like item that you wonder > >what the heck is wrong. > > > >mag > > > > > >From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On > >Behalf Of Hudson, Scott > >Sent: Tuesday, July 07, 2015 11:59 AM > >To: Bob Thomas; Eliot Kimber > >Cc: DITA TC > >Subject: Re: [dita] Index in the PDF version of the spec? > > > > > > > >I think it is useful to provide a quality index for the specification. As > >such, I also agree with Bob below. I think prolog indexterms should apply > >to the entire scope of the topic, while inlines should also be used when > >necessary. Since a lot of the spec has been broken into smaller > >components, I also hope it is true that we should be able to stick with > >the prolog approach in general. I do not want to rule out using the > >inline terms, though. > > > > > > > >Thanks and best regards, > > > > > > > >Scott Hudson > > > >Senior Consultant > > > >Comtech Services Inc. > > > >303-232-7586 > > > > > > > > > > > > > > > > > >From: <dita@lists.oasis-open.org> on behalf of Bob Thomas > >Date: Tuesday, July 7, 2015 at 8:31 AM > >To: Eliot Kimber > >Cc: DITA TC > >Subject: Re: [dita] Index in the PDF version of the spec? > > > > > > > >An index can be one of the better ways of finding things without having > >to take a drink out of the firehose that is search. > > > > > >I agree with Eliot's position on inline vs. prolog. The only index terms > >in the prolog should be those that correspond with the entire scope of > >the topic. In general (i.e., not just the spec), writing shorter tightly > >scoped topics increases the likelihood that index terms will be in the > >prolog rather than inline. > > > > > > > >Best Regards, > > > >Bob > > > > > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber <ekimber@contrext.com> wrote: > >I agree that an index is important. > > > >But I also feel very strongly that if the index entries are not in line, > >the index should not be produced in PDF, for the simple reason that it > >will result in many page number references that are wrong (because they > >will point to the start of the topic rather than the place where the term > >actually occurs). > > > >Readers will not understand or care why the page number references are > >wrong and will assume that either we did poor job of indexing or assume > >that DITA's normal PDF production tools can't do indexing properly, > >neither of which is the case. > > > >So while having an index is important, if we can't put the index entries > >in the source at the point of occurrence of the terms indexed then we > >should not produce the index for PDF. > > > >I know from painful experience how much work it is to put index entries > >inline if you aren't doing it as you write. > > > >Cheers, > > > >Eliot > >---- > >Eliot Kimber, Owner > >Contrext, LLC > > http://contrext.com > > > > > > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" <dita@lists.oasis-open.org on > >behalf of kris@eberleinconsulting.com> wrote: > > > >>Background: > >> > >>We removed the index from the 1.2 specification because it was of > >>extremely low quality. Since then, Robert and I have been improving the > >>indexing as we can (placing all <indexterm> elements in the prolog), > >>although there still are many holes. > >> > >>We *can* index during the forthcoming 30-day review, and I have several > >>folks who have volunteered to work together under rigid guidelines to do > >>so. > >> > >>Shall we move forward with this? I'm old school; I firmly believe that > >>an index is an important and necessary entry point to information, and I > >>don't think that online search can replace it. > >> > >>Let's talk about this. I know that we have TC members who think that an > >>index is unprofessional in PDF output unless the <indexterm> entries are > >>placed in-text. > >> > >>-- > >>Best, > >>Kris > >> > >>Kristen James Eberlein > >>Chair, OASIS DITA Technical Committee > >>Principal consultant, Eberlein Consulting > >>www.eberleinconsulting.com < http://www.eberleinconsulting.com > > >>+1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) > >> > >> > >>--------------------------------------------------------------------- > >>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 > >> > >> > > > > > > > >--------------------------------------------------------------------- > >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 > > > > > > > > > > > > > > > > > >-- > >Bob Thomas > >+1 720 201 8260 > > > >Skype: bob.thomas.colorado > > > >Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype > > > >Time zone: Mountain (GMT-7) > > > > > > > > -- > Bob Thomas > +1 720 201 8260 > Skype: bob.thomas.colorado > Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype > Time zone: Mountain (GMT-7) > > [image removed] > > > -- > Bob Thomas > +1 720 201 8260 > Skype: bob.thomas.colorado > Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype > Time zone: Mountain (GMT-7) > > [image removed]

Excellent plan! JoAnn T. Hackos, PhD President Comtech Services Inc. 710 Kipling Street, Suite 400 Denver, CO 80215 Joann.hackos@comtech-serv.com 303-232-7586   We will be hosting the CIDM Online Conference on July 29, 2015   More information is available:  https://forum.infomanagementcenter.com From: Robert Anderson < robander@us.ibm.com > Date: Wednesday, July 8, 2015 at 1:04 PM To: Bob Thomas < bob.thomas@tagsmiths.com > Cc: DITA TC < dita@lists.oasis-open.org > Subject: Re: [dita] Index in the PDF version of the spec? Caveat: I am not a member of the Brotherhood of Professional Indexers so my question/comment here may seem naive. > I can think of three choices: 1) no index, 2) add the @start > attribute to all leaf-node indexterms in the prolog, 3) abandon > prolog/keywords/indexterm entirely and use inline markup only. One of the index entries Kris added for "controlled values" currently takes me to the topic "Binding controlled values to an attribute". The title and first paragraphs are all clearly related to the subject. If I follow that index entry to that topic, and only find a title plus one paragraphs before the page ends, I'm not going to stop reading, regardless of whether the index itself linked to "page x" versus "page x to X+1". Are others likely to get annoyed because the index didn't warn ahead of time that the topic continued to a second page? Most (not all) of the topics we should index are short enough that they will appear on one or two pages. Implementing suggestion #2 for will mean the majority of our entries change from something like "123" to "123-124". Moving all index terms to the body (suggestion #3) would mean each index target appears only with the first paragraph, after the title and short description. There will be situations where the title and short description are on the previous page, meaning we're back in the "obviously bad" scenario of going to the wrong location. I started this note 90 minutes ago and now see one from Michael that makes sense to me. 2 simple rules, based on the content we find (rather than rules based on what we assume we will find). Quoting Michael, with one (addition): - if the topic title (or short description) mentions the subject, put the index item in the prolog - if it doesn't, put the index item as close to the subject matter as possible Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) < dita@lists.oasis-open.org > wrote on 07/08/2015 12:03:58: > From: Bob Thomas < bob.thomas@tagsmiths.com > > To: Eliot Kimber < ekimber@contrext.com > > Cc: Tom Magliery < tom.magliery@justsystems.com >, "Hudson, Scott" > < scott.hudson@comtech-serv.com >, DITA TC < dita@lists.oasis-open.org > > Date: 07/08/2015 12:04 > Subject: Re: [dita] Index in the PDF version of the spec? > Sent by: < dita@lists.oasis-open.org > > > Earlier I said: > > "Now, back to page numbering. If you restrict prolog index terms to > those that correspond to the topic scope, there is never a case > where the index will display an incorrect page number for such terms." > > I withdraw this claim. Here is why. Suppose you have a topic that > covers branch filtering. The index term "conditional processing" > would apply to the entire topic. However, the text in the topic does > not mention conditional processing by name until the last half of > the topic. We are still logically correct in associating the > "conditional processing" with the topic, but the reader knows > nothing about our notions of scope, and when the first mention of > "conditional processing" falls a page other than where the topic > began the reader perceives that we are incompetent. This is > essentially the same thing that Eliot said earlier, but I was too > anchored to the notion of using indexterm in prolog to understand it. > > I can think of three choices: 1) no index, 2) add the @start > attribute to all leaf-node indexterms in the prolog, 3) abandon > prolog/keywords/indexterm entirely and use inline markup only. > > Best Regards, > Bob > > On Wed, Jul 8, 2015 at 8:55 AM, Bob Thomas < bob.thomas@tagsmiths.com > wrote: > I also insist that fidelity between index-referenced content and > page numbers is essential. Beyond that, I argue in this message that > 1) prolog is the only appropriate place for index terms that pertain > to an entire topic, and 2) prolog is inappropriate for index terms > that do not pertain to the entire topic. > > First, I believe that prolog/keywords/indexterm is the only > appropriate place for index terms that pertain to an entire topic. > Semantically, this makes sense because of the prolog element's > position in the topic structure. But, let's consider the > alternative. Suppose that we never use prolog for index terms and > restrict ourselves to using only inline index markup. In this > scenario, index terms that apply to the entire topic would > presumably appear at the first opportunity in the topic structure > (in Xpath, this would be /topic/body/*[1] or one of its > descendants). Such markup violates the semantic intent of the > vocabulary because the index term's containing element constitutes > an implicit scope, and that scope won't usually match the topic scope. > > Now, back to page numbering. If you restrict prolog index terms to > those that correspond to the topic scope, there is never a case > where the index will display an incorrect page number for such terms. > > Second, if you place index terms in prolog that do not pertain to > the entire topic, then you will likely have page numbers in the > index that do not correspond to the content's location in the > output. I agree with Eliot's assessment about our audience (this is > also why I have been such a prig about wording during the review > cycle). Consequently, I would rather not have an Index if the page > numbering is going to be wrong upon occasion. > > Best Regards, > Bob > > On Wed, Jul 8, 2015 at 7:48 AM, Eliot Kimber < ekimber@contrext.com > wrote: > I don't agree with this heuristic. > > I hate to be difficult about this, but our audience is by and large > technical communicators, people who have specific knowledge of and > expectations for indexes. Thus they are likely to be the most critical > audience possible, short of the members of the International Brotherhood > of Professional Indexers. > > If the page number reference does not take you to the page where the thing > indexed occurs they will notice and wonder why *and blame DITA for the > failure*. Not the indexers, not the PDF generation process, not the Open > Toolkit, DITA. > > That's my concern. > > We already have a huge problem in the community with statements like "DITA > produces crappy print output". Having the DITA governing body produce a > print document with what appear to be bad indexing would only exacerbate > the problem. > > Cheers, > > E. > > > ---- > Eliot Kimber, Owner > Contrext, LLC > http://contrext.com > > > > > On 7/7/15, 2:13 PM, "Tom Magliery" < dita@lists.oasis-open.org on behalf of > tom.magliery@justsystems.com > wrote: > > >Here's a proposed heuristic that I think might get close to everyone's > >intuition here: > > > >An <indexterm> should occur inline if and only if the location to which > >the reader is directed from the index will occur under a bolded > >(sub)heading that is NOT the topic title. In that case the indexterm > >should appear at the location of the nearest bolded subheading. > > > >I arrived at this idea after pondering Eliot's remark about users not > >understanding/caring about incorrect page numbers. My thought is that the > >reader will be tolerant enough to accept a jump to the nearest "title" > >(section/topic/whatever) and scan the text from there. It's not until you > >(the reader's) eye hits another bolded title-like item that you wonder > >what the heck is wrong. > > > >mag > > > > > >From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On > >Behalf Of Hudson, Scott > >Sent: Tuesday, July 07, 2015 11:59 AM > >To: Bob Thomas; Eliot Kimber > >Cc: DITA TC > >Subject: Re: [dita] Index in the PDF version of the spec? > > > > > > > >I think it is useful to provide a quality index for the specification. As > >such, I also agree with Bob below. I think prolog indexterms should apply > >to the entire scope of the topic, while inlines should also be used when > >necessary. Since a lot of the spec has been broken into smaller > >components, I also hope it is true that we should be able to stick with > >the prolog approach in general. I do not want to rule out using the > >inline terms, though. > > > > > > > >Thanks and best regards, > > > > > > > >Scott Hudson > > > >Senior Consultant > > > >Comtech Services Inc. > > > >303-232-7586 > > > > > > > > > > > > > > > > > >From: < dita@lists.oasis-open.org > on behalf of Bob Thomas > >Date: Tuesday, July 7, 2015 at 8:31 AM > >To: Eliot Kimber > >Cc: DITA TC > >Subject: Re: [dita] Index in the PDF version of the spec? > > > > > > > >An index can be one of the better ways of finding things without having > >to take a drink out of the firehose that is search. > > > > > >I agree with Eliot's position on inline vs. prolog. The only index terms > >in the prolog should be those that correspond with the entire scope of > >the topic. In general (i.e., not just the spec), writing shorter tightly > >scoped topics increases the likelihood that index terms will be in the > >prolog rather than inline. > > > > > > > >Best Regards, > > > >Bob > > > > > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber < ekimber@contrext.com > wrote: > >I agree that an index is important. > > > >But I also feel very strongly that if the index entries are not in line, > >the index should not be produced in PDF, for the simple reason that it > >will result in many page number references that are wrong (because they > >will point to the start of the topic rather than the place where the term > >actually occurs). > > > >Readers will not understand or care why the page number references are > >wrong and will assume that either we did poor job of indexing or assume > >that DITA's normal PDF production tools can't do indexing properly, > >neither of which is the case. > > > >So while having an index is important, if we can't put the index entries > >in the source at the point of occurrence of the terms indexed then we > >should not produce the index for PDF. > > > >I know from painful experience how much work it is to put index entries > >inline if you aren't doing it as you write. > > > >Cheers, > > > >Eliot > >---- > >Eliot Kimber, Owner > >Contrext, LLC > > http://contrext.com > > > > > > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on > >behalf of kris@eberleinconsulting.com > wrote: > > > >>Background: > >> > >>We removed the index from the 1.2 specification because it was of > >>extremely low quality. Since then, Robert and I have been improving the > >>indexing as we can (placing all <indexterm> elements in the prolog), > >>although there still are many holes. > >> > >>We *can* index during the forthcoming 30-day review, and I have several > >>folks who have volunteered to work together under rigid guidelines to do > >>so. > >> > >>Shall we move forward with this? I'm old school; I firmly believe that > >>an index is an important and necessary entry point to information, and I > >>don't think that online search can replace it. > >> > >>Let's talk about this. I know that we have TC members who think that an > >>index is unprofessional in PDF output unless the <indexterm> entries are > >>placed in-text. > >> > >>-- > >>Best, > >>Kris > >> > >>Kristen James Eberlein > >>Chair, OASIS DITA Technical Committee > >>Principal consultant, Eberlein Consulting > >>www.eberleinconsulting.com < http://www.eberleinconsulting.com > > >>+1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) > >> > >> > >>--------------------------------------------------------------------- > >>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 > >> > >> > > > > > > > >--------------------------------------------------------------------- > >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 > > > > > > > > > > > > > > > > > >-- > >Bob Thomas > >+1 720 201 8260 > > > >Skype: bob.thomas.colorado > > > >Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > > > >Time zone: Mountain (GMT-7) > > > > > > > > -- > Bob Thomas > +1 720 201 8260 > Skype: bob.thomas.colorado > Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > Time zone: Mountain (GMT-7) > > [image removed] > > > -- > Bob Thomas > +1 720 201 8260 > Skype: bob.thomas.colorado > Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > Time zone: Mountain (GMT-7) > > [image removed]

Not being much of a contributor, I hesitate to weigh in, but.... I think it’s generally considered problematic for translation to include <indexterm> inline. At present the spec isn’t translated (officially) and maybe there are no plans to do so, but plans can change. Would it be a limiting move to do something that would make translation more difficult in the future?   Leigh   DITA TC dita@lists.oasis-open.org r Leigh White DITA Specialist   IXIASOFT  825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1 tel  + 1 514 279-4942  /  toll free + 1 877 279-4942 (GMT -6:00) leigh.white@ixiasoft.com  /  www.ixiasoft.com         From: Hackos, Joann [mailto:joann.hackos@comtech-serv.com] Sent: Wednesday, July 8, 2015 2:20 PM To: Robert D Anderson; Bob Thomas Cc: DITA TC Subject: Re: [dita] Index in the PDF version of the spec?   Excellent plan!   JoAnn T. Hackos, PhD President Comtech Services Inc. 710 Kipling Street, Suite 400 Denver, CO 80215 Joann.hackos@comtech-serv.com 303-232-7586       We will be hosting the CIDM Online Conference on July 29, 2015   More information is available:  https://forum.infomanagementcenter.com   From: Robert Anderson < robander@us.ibm.com > Date: Wednesday, July 8, 2015 at 1:04 PM To: Bob Thomas < bob.thomas@tagsmiths.com > Cc: DITA TC < dita@lists.oasis-open.org > Subject: Re: [dita] Index in the PDF version of the spec?   Caveat: I am not a member of the Brotherhood of Professional Indexers so my question/comment here may seem naive. > I can think of three choices: 1) no index, 2) add the @start > attribute to all leaf-node indexterms in the prolog, 3) abandon > prolog/keywords/indexterm entirely and use inline markup only. One of the index entries Kris added for "controlled values" currently takes me to the topic "Binding controlled values to an attribute". The title and first paragraphs are all clearly related to the subject. If I follow that index entry to that topic, and only find a title plus one paragraphs before the page ends, I'm not going to stop reading, regardless of whether the index itself linked to "page x" versus "page x to X+1". Are others likely to get annoyed because the index didn't warn ahead of time that the topic continued to a second page? Most (not all) of the topics we should index are short enough that they will appear on one or two pages. Implementing suggestion #2 for will mean the majority of our entries change from something like "123" to "123-124". Moving all index terms to the body (suggestion #3) would mean each index target appears only with the first paragraph, after the title and short description. There will be situations where the title and short description are on the previous page, meaning we're back in the "obviously bad" scenario of going to the wrong location. I started this note 90 minutes ago and now see one from Michael that makes sense to me. 2 simple rules, based on the content we find (rather than rules based on what we assume we will find). Quoting Michael, with one (addition): - if the topic title (or short description) mentions the subject, put the index item in the prolog - if it doesn't, put the index item as close to the subject matter as possible Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) < dita@lists.oasis-open.org > wrote on 07/08/2015 12:03:58: > From: Bob Thomas < bob.thomas@tagsmiths.com > > To: Eliot Kimber < ekimber@contrext.com > > Cc: Tom Magliery < tom.magliery@justsystems.com >, "Hudson, Scott" > < scott.hudson@comtech-serv.com >, DITA TC < dita@lists.oasis-open.org > > Date: 07/08/2015 12:04 > Subject: Re: [dita] Index in the PDF version of the spec? > Sent by: < dita@lists.oasis-open.org > > > Earlier I said: > > "Now, back to page numbering. If you restrict prolog index terms to > those that correspond to the topic scope, there is never a case > where the index will display an incorrect page number for such terms." > > I withdraw this claim. Here is why. Suppose you have a topic that > covers branch filtering. The index term "conditional processing" > would apply to the entire topic. However, the text in the topic does > not mention conditional processing by name until the last half of > the topic. We are still logically correct in associating the > "conditional processing" with the topic, but the reader knows > nothing about our notions of scope, and when the first mention of > "conditional processing" falls a page other than where the topic > began the reader perceives that we are incompetent. This is > essentially the same thing that Eliot said earlier, but I was too > anchored to the notion of using indexterm in prolog to understand it. > > I can think of three choices: 1) no index, 2) add the @start > attribute to all leaf-node indexterms in the prolog, 3) abandon > prolog/keywords/indexterm entirely and use inline markup only. > > Best Regards, > Bob > > On Wed, Jul 8, 2015 at 8:55 AM, Bob Thomas < bob.thomas@tagsmiths.com > wrote: > I also insist that fidelity between index-referenced content and > page numbers is essential. Beyond that, I argue in this message that > 1) prolog is the only appropriate place for index terms that pertain > to an entire topic, and 2) prolog is inappropriate for index terms > that do not pertain to the entire topic. > > First, I believe that prolog/keywords/indexterm is the only > appropriate place for index terms that pertain to an entire topic. > Semantically, this makes sense because of the prolog element's > position in the topic structure. But, let's consider the > alternative. Suppose that we never use prolog for index terms and > restrict ourselves to using only inline index markup. In this > scenario, index terms that apply to the entire topic would > presumably appear at the first opportunity in the topic structure > (in Xpath, this would be /topic/body/*[1] or one of its > descendants). Such markup violates the semantic intent of the > vocabulary because the index term's containing element constitutes > an implicit scope, and that scope won't usually match the topic scope. > > Now, back to page numbering. If you restrict prolog index terms to > those that correspond to the topic scope, there is never a case > where the index will display an incorrect page number for such terms. > > Second, if you place index terms in prolog that do not pertain to > the entire topic, then you will likely have page numbers in the > index that do not correspond to the content's location in the > output. I agree with Eliot's assessment about our audience (this is > also why I have been such a prig about wording during the review > cycle). Consequently, I would rather not have an Index if the page > numbering is going to be wrong upon occasion. > > Best Regards, > Bob > > On Wed, Jul 8, 2015 at 7:48 AM, Eliot Kimber < ekimber@contrext.com > wrote: > I don't agree with this heuristic. > > I hate to be difficult about this, but our audience is by and large > technical communicators, people who have specific knowledge of and > expectations for indexes. Thus they are likely to be the most critical > audience possible, short of the members of the International Brotherhood > of Professional Indexers. > > If the page number reference does not take you to the page where the thing > indexed occurs they will notice and wonder why *and blame DITA for the > failure*. Not the indexers, not the PDF generation process, not the Open > Toolkit, DITA. > > That's my concern. > > We already have a huge problem in the community with statements like "DITA > produces crappy print output". Having the DITA governing body produce a > print document with what appear to be bad indexing would only exacerbate > the problem. > > Cheers, > > E. > > > ---- > Eliot Kimber, Owner > Contrext, LLC > http://contrext.com > > > > > On 7/7/15, 2:13 PM, "Tom Magliery" < dita@lists.oasis-open.org on behalf of > tom.magliery@justsystems.com > wrote: > > >Here's a proposed heuristic that I think might get close to everyone's > >intuition here: > > > >An <indexterm> should occur inline if and only if the location to which > >the reader is directed from the index will occur under a bolded > >(sub)heading that is NOT the topic title. In that case the indexterm > >should appear at the location of the nearest bolded subheading. > > > >I arrived at this idea after pondering Eliot's remark about users not > >understanding/caring about incorrect page numbers. My thought is that the > >reader will be tolerant enough to accept a jump to the nearest "title" > >(section/topic/whatever) and scan the text from there. It's not until you > >(the reader's) eye hits another bolded title-like item that you wonder > >what the heck is wrong. > > > >mag > > > > > >From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On > >Behalf Of Hudson, Scott > >Sent: Tuesday, July 07, 2015 11:59 AM > >To: Bob Thomas; Eliot Kimber > >Cc: DITA TC > >Subject: Re: [dita] Index in the PDF version of the spec? > > > > > > > >I think it is useful to provide a quality index for the specification. As > >such, I also agree with Bob below. I think prolog indexterms should apply > >to the entire scope of the topic, while inlines should also be used when > >necessary. Since a lot of the spec has been broken into smaller > >components, I also hope it is true that we should be able to stick with > >the prolog approach in general. I do not want to rule out using the > >inline terms, though. > > > > > > > >Thanks and best regards, > > > > > > > >Scott Hudson > > > >Senior Consultant > > > >Comtech Services Inc. > > > >303-232-7586 > > > > > > > > > > > > > > > > > >From: < dita@lists.oasis-open.org > on behalf of Bob Thomas > >Date: Tuesday, July 7, 2015 at 8:31 AM > >To: Eliot Kimber > >Cc: DITA TC > >Subject: Re: [dita] Index in the PDF version of the spec? > > > > > > > >An index can be one of the better ways of finding things without having > >to take a drink out of the firehose that is search. > > > > > >I agree with Eliot's position on inline vs. prolog. The only index terms > >in the prolog should be those that correspond with the entire scope of > >the topic. In general (i.e., not just the spec), writing shorter tightly > >scoped topics increases the likelihood that index terms will be in the > >prolog rather than inline. > > > > > > > >Best Regards, > > > >Bob > > > > > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber < ekimber@contrext.com > wrote: > >I agree that an index is important. > > > >But I also feel very strongly that if the index entries are not in line, > >the index should not be produced in PDF, for the simple reason that it > >will result in many page number references that are wrong (because they > >will point to the start of the topic rather than the place where the term > >actually occurs). > > > >Readers will not understand or care why the page number references are > >wrong and will assume that either we did poor job of indexing or assume > >that DITA's normal PDF production tools can't do indexing properly, > >neither of which is the case. > > > >So while having an index is important, if we can't put the index entries > >in the source at the point of occurrence of the terms indexed then we > >should not produce the index for PDF. > > > >I know from painful experience how much work it is to put index entries > >inline if you aren't doing it as you write. > > > >Cheers, > > > >Eliot > >---- > >Eliot Kimber, Owner > >Contrext, LLC > > http://contrext.com > > > > > > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on > >behalf of kris@eberleinconsulting.com > wrote: > > > >>Background: > >> > >>We removed the index from the 1.2 specification because it was of > >>extremely low quality. Since then, Robert and I have been improving the > >>indexing as we can (placing all <indexterm> elements in the prolog), > >>although there still are many holes. > >> > >>We *can* index during the forthcoming 30-day review, and I have several > >>folks who have volunteered to work together under rigid guidelines to do > >>so. > >> > >>Shall we move forward with this? I'm old school; I firmly believe that > >>an index is an important and necessary entry point to information, and I > >>don't think that online search can replace it. > >> > >>Let's talk about this. I know that we have TC members who think that an > >>index is unprofessional in PDF output unless the <indexterm> entries are > >>placed in-text. > >> > >>-- > >>Best, > >>Kris > >> > >>Kristen James Eberlein > >>Chair, OASIS DITA Technical Committee > >>Principal consultant, Eberlein Consulting > >> www.eberleinconsulting.com < http://www.eberleinconsulting.com > > >>+1 919 682-2290 < tel:%2B1%20919%20682-2290 >; kriseberlein (skype) > >> > >> > >>--------------------------------------------------------------------- > >>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 > >> > >> > > > > > > > >--------------------------------------------------------------------- > >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 > > > > > > > > > > > > > > > > > >-- > >Bob Thomas > >+1 720 201 8260 > > > >Skype: bob.thomas.colorado > > > >Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > > > >Time zone: Mountain (GMT-7) > > > > > > > > -- > Bob Thomas > +1 720 201 8260 > Skype: bob.thomas.colorado > Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > Time zone: Mountain (GMT-7) > > [image removed] > > > -- > Bob Thomas > +1 720 201 8260 > Skype: bob.thomas.colorado > Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > Time zone: Mountain (GMT-7) > > [image removed]

Actually, we published an Adoption TC Feature article on this. As long as the index term is immediately after the tag <p><index term ... >the text ... The translation tools remove the index term to be translated separately. JoAnn  Sent from my iPad JoAnn Hackos President Comtech Services Inc 710 Kipling Street Suite 400 Lakewood CO 80215 303-232-7586   We will be hosting the CIDM Online Conference  on July 29, 2015    More information is available at  https://forum.infomanagementcenter.com On Jul 8, 2015, at 6:25 PM, Leigh White < Leigh.White@ixiasoft.com > wrote: Not being much of a contributor, I hesitate to weigh in, but.... I think it’s generally considered problematic for translation to include <indexterm> inline. At present the spec isn’t translated (officially) and maybe there are no plans to do so, but plans can change. Would it be a limiting move to do something that would make translation more difficult in the future?   Leigh   DITA TC dita@lists.oasis-open.org r Leigh White DITA Specialist   IXIASOFT  825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1 tel  + 1 514 279-4942  /  toll free + 1 877 279-4942 (GMT -6:00) leigh.white@ixiasoft.com  /  www.ixiasoft.com         From: Hackos, Joann [ mailto:joann.hackos@comtech-serv.com ] Sent: Wednesday, July 8, 2015 2:20 PM To: Robert D Anderson; Bob Thomas Cc: DITA TC Subject: Re: [dita] Index in the PDF version of the spec?   Excellent plan!   JoAnn T. Hackos, PhD President Comtech Services Inc. 710 Kipling Street, Suite 400 Denver, CO 80215 Joann.hackos@comtech-serv.com 303-232-7586     <image002.png>   We will be hosting the CIDM Online Conference on July 29, 2015   More information is available:  https://forum.infomanagementcenter.com   From: Robert Anderson < robander@us.ibm.com > Date: Wednesday, July 8, 2015 at 1:04 PM To: Bob Thomas < bob.thomas@tagsmiths.com > Cc: DITA TC < dita@lists.oasis-open.org > Subject: Re: [dita] Index in the PDF version of the spec?   Caveat: I am not a member of the Brotherhood of Professional Indexers so my question/comment here may seem naive. > I can think of three choices: 1) no index, 2) add the @start > attribute to all leaf-node indexterms in the prolog, 3) abandon > prolog/keywords/indexterm entirely and use inline markup only. One of the index entries Kris added for "controlled values" currently takes me to the topic "Binding controlled values to an attribute". The title and first paragraphs are all clearly related to the subject. If I follow that index entry to that topic, and only find a title plus one paragraphs before the page ends, I'm not going to stop reading, regardless of whether the index itself linked to "page x" versus "page x to X+1". Are others likely to get annoyed because the index didn't warn ahead of time that the topic continued to a second page? Most (not all) of the topics we should index are short enough that they will appear on one or two pages. Implementing suggestion #2 for will mean the majority of our entries change from something like "123" to "123-124". Moving all index terms to the body (suggestion #3) would mean each index target appears only with the first paragraph, after the title and short description. There will be situations where the title and short description are on the previous page, meaning we're back in the "obviously bad" scenario of going to the wrong location. I started this note 90 minutes ago and now see one from Michael that makes sense to me. 2 simple rules, based on the content we find (rather than rules based on what we assume we will find). Quoting Michael, with one (addition): - if the topic title (or short description) mentions the subject, put the index item in the prolog - if it doesn't, put the index item as close to the subject matter as possible Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) < dita@lists.oasis-open.org > wrote on 07/08/2015 12:03:58: > From: Bob Thomas < bob.thomas@tagsmiths.com > > To: Eliot Kimber < ekimber@contrext.com > > Cc: Tom Magliery < tom.magliery@justsystems.com >, "Hudson, Scott" > < scott.hudson@comtech-serv.com >, DITA TC < dita@lists.oasis-open.org > > Date: 07/08/2015 12:04 > Subject: Re: [dita] Index in the PDF version of the spec? > Sent by: < dita@lists.oasis-open.org > > > Earlier I said: > > "Now, back to page numbering. If you restrict prolog index terms to > those that correspond to the topic scope, there is never a case > where the index will display an incorrect page number for such terms." > > I withdraw this claim. Here is why. Suppose you have a topic that > covers branch filtering. The index term "conditional processing" > would apply to the entire topic. However, the text in the topic does > not mention conditional processing by name until the last half of > the topic. We are still logically correct in associating the > "conditional processing" with the topic, but the reader knows > nothing about our notions of scope, and when the first mention of > "conditional processing" falls a page other than where the topic > began the reader perceives that we are incompetent. This is > essentially the same thing that Eliot said earlier, but I was too > anchored to the notion of using indexterm in prolog to understand it. > > I can think of three choices: 1) no index, 2) add the @start > attribute to all leaf-node indexterms in the prolog, 3) abandon > prolog/keywords/indexterm entirely and use inline markup only. > > Best Regards, > Bob > > On Wed, Jul 8, 2015 at 8:55 AM, Bob Thomas < bob.thomas@tagsmiths.com > wrote: > I also insist that fidelity between index-referenced content and > page numbers is essential. Beyond that, I argue in this message that > 1) prolog is the only appropriate place for index terms that pertain > to an entire topic, and 2) prolog is inappropriate for index terms > that do not pertain to the entire topic. > > First, I believe that prolog/keywords/indexterm is the only > appropriate place for index terms that pertain to an entire topic. > Semantically, this makes sense because of the prolog element's > position in the topic structure. But, let's consider the > alternative. Suppose that we never use prolog for index terms and > restrict ourselves to using only inline index markup. In this > scenario, index terms that apply to the entire topic would > presumably appear at the first opportunity in the topic structure > (in Xpath, this would be /topic/body/*[1] or one of its > descendants). Such markup violates the semantic intent of the > vocabulary because the index term's containing element constitutes > an implicit scope, and that scope won't usually match the topic scope. > > Now, back to page numbering. If you restrict prolog index terms to > those that correspond to the topic scope, there is never a case > where the index will display an incorrect page number for such terms. > > Second, if you place index terms in prolog that do not pertain to > the entire topic, then you will likely have page numbers in the > index that do not correspond to the content's location in the > output. I agree with Eliot's assessment about our audience (this is > also why I have been such a prig about wording during the review > cycle). Consequently, I would rather not have an Index if the page > numbering is going to be wrong upon occasion. > > Best Regards, > Bob > > On Wed, Jul 8, 2015 at 7:48 AM, Eliot Kimber < ekimber@contrext.com > wrote: > I don't agree with this heuristic. > > I hate to be difficult about this, but our audience is by and large > technical communicators, people who have specific knowledge of and > expectations for indexes. Thus they are likely to be the most critical > audience possible, short of the members of the International Brotherhood > of Professional Indexers. > > If the page number reference does not take you to the page where the thing > indexed occurs they will notice and wonder why *and blame DITA for the > failure*. Not the indexers, not the PDF generation process, not the Open > Toolkit, DITA. > > That's my concern. > > We already have a huge problem in the community with statements like "DITA > produces crappy print output". Having the DITA governing body produce a > print document with what appear to be bad indexing would only exacerbate > the problem. > > Cheers, > > E. > > > ---- > Eliot Kimber, Owner > Contrext, LLC > http://contrext.com > > > > > On 7/7/15, 2:13 PM, "Tom Magliery" < dita@lists.oasis-open.org on behalf of > tom.magliery@justsystems.com > wrote: > > >Here's a proposed heuristic that I think might get close to everyone's > >intuition here: > > > >An <indexterm> should occur inline if and only if the location to which > >the reader is directed from the index will occur under a bolded > >(sub)heading that is NOT the topic title. In that case the indexterm > >should appear at the location of the nearest bolded subheading. > > > >I arrived at this idea after pondering Eliot's remark about users not > >understanding/caring about incorrect page numbers. My thought is that the > >reader will be tolerant enough to accept a jump to the nearest "title" > >(section/topic/whatever) and scan the text from there. It's not until you > >(the reader's) eye hits another bolded title-like item that you wonder > >what the heck is wrong. > > > >mag > > > > > >From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On > >Behalf Of Hudson, Scott > >Sent: Tuesday, July 07, 2015 11:59 AM > >To: Bob Thomas; Eliot Kimber > >Cc: DITA TC > >Subject: Re: [dita] Index in the PDF version of the spec? > > > > > > > >I think it is useful to provide a quality index for the specification. As > >such, I also agree with Bob below. I think prolog indexterms should apply > >to the entire scope of the topic, while inlines should also be used when > >necessary. Since a lot of the spec has been broken into smaller > >components, I also hope it is true that we should be able to stick with > >the prolog approach in general. I do not want to rule out using the > >inline terms, though. > > > > > > > >Thanks and best regards, > > > > > > > >Scott Hudson > > > >Senior Consultant > > > >Comtech Services Inc. > > > >303-232-7586 > > > > > > > > > > > > > > > > > >From: < dita@lists.oasis-open.org > on behalf of Bob Thomas > >Date: Tuesday, July 7, 2015 at 8:31 AM > >To: Eliot Kimber > >Cc: DITA TC > >Subject: Re: [dita] Index in the PDF version of the spec? > > > > > > > >An index can be one of the better ways of finding things without having > >to take a drink out of the firehose that is search. > > > > > >I agree with Eliot's position on inline vs. prolog. The only index terms > >in the prolog should be those that correspond with the entire scope of > >the topic. In general (i.e., not just the spec), writing shorter tightly > >scoped topics increases the likelihood that index terms will be in the > >prolog rather than inline. > > > > > > > >Best Regards, > > > >Bob > > > > > > > >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber < ekimber@contrext.com > wrote: > >I agree that an index is important. > > > >But I also feel very strongly that if the index entries are not in line, > >the index should not be produced in PDF, for the simple reason that it > >will result in many page number references that are wrong (because they > >will point to the start of the topic rather than the place where the term > >actually occurs). > > > >Readers will not understand or care why the page number references are > >wrong and will assume that either we did poor job of indexing or assume > >that DITA's normal PDF production tools can't do indexing properly, > >neither of which is the case. > > > >So while having an index is important, if we can't put the index entries > >in the source at the point of occurrence of the terms indexed then we > >should not produce the index for PDF. > > > >I know from painful experience how much work it is to put index entries > >inline if you aren't doing it as you write. > > > >Cheers, > > > >Eliot > >---- > >Eliot Kimber, Owner > >Contrext, LLC > > http://contrext.com > > > > > > > > > >On 7/7/15, 9:00 AM, "Kristen James Eberlein" < dita@lists.oasis-open.org on > >behalf of kris@eberleinconsulting.com > wrote: > > > >>Background: > >> > >>We removed the index from the 1.2 specification because it was of > >>extremely low quality. Since then, Robert and I have been improving the > >>indexing as we can (placing all <indexterm> elements in the prolog), > >>although there still are many holes. > >> > >>We *can* index during the forthcoming 30-day review, and I have several > >>folks who have volunteered to work together under rigid guidelines to do > >>so. > >> > >>Shall we move forward with this? I'm old school; I firmly believe that > >>an index is an important and necessary entry point to information, and I > >>don't think that online search can replace it. > >> > >>Let's talk about this. I know that we have TC members who think that an > >>index is unprofessional in PDF output unless the <indexterm> entries are > >>placed in-text. > >> > >>-- > >>Best, > >>Kris > >> > >>Kristen James Eberlein > >>Chair, OASIS DITA Technical Committee > >>Principal consultant, Eberlein Consulting > >> www.eberleinconsulting.com < http://www.eberleinconsulting.com > > >>+1 919 682-2290 < tel:%2B1%20919%20682-2290 >; kriseberlein (skype) > >> > >> > >>--------------------------------------------------------------------- > >>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 > >> > >> > > > > > > > >--------------------------------------------------------------------- > >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 > > > > > > > > > > > > > > > > > >-- > >Bob Thomas > >+1 720 201 8260 > > > >Skype: bob.thomas.colorado > > > >Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > > > >Time zone: Mountain (GMT-7) > > > > > > > > -- > Bob Thomas > +1 720 201 8260 > Skype: bob.thomas.colorado > Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > Time zone: Mountain (GMT-7) > > [image removed] > > > -- > Bob Thomas > +1 720 201 8260 > Skype: bob.thomas.colorado > Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype > Time zone: Mountain (GMT-7) > > [image removed] Attachment: image001.jpg Description: image001.jpg

That seems reasonable to me. If the title clearly reflects the index term then there's no problem having the index entry take you to the page that title is on. Of course, in the ideal index, most of the terms are *not* in the titles, since part of the point of an index is to relate non-obvious things to their locations in the doc. It is the case that this document, and standards in general, tend to be pretty heading heavy. But I realize that that level of indexing is way beyond any indexing effort scope we might have. Cheers, E. ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com On 7/8/15, 2:04 PM, "Robert D Anderson" <dita@lists.oasis-open.org on behalf of robander@us.ibm.com> wrote: >Caveat: I am not a member of the Brotherhood of Professional Indexers so >my question/comment here may seem naive. > >> I can think of three choices: 1) no index, 2) add the @start >> attribute to all leaf-node indexterms in the prolog, 3) abandon >> prolog/keywords/indexterm entirely and use inline markup only. > >One of the index entries Kris added for "controlled values" currently >takes me to the topic "Binding controlled values to an attribute". The >title and first paragraphs are all clearly related to the subject. If I >follow that index entry to that topic, and only find a title plus one >paragraphs before the page ends, I'm not going to stop reading, >regardless of whether the index itself linked to "page x" versus "page x >to X+1". Are others likely to get annoyed because the index didn't warn >ahead of time that the topic continued to a second page? > >Most (not all) of the topics we should index are short enough that they >will appear on one or two pages. Implementing suggestion #2 for will mean >the majority of our entries change from something like "123" to >"123-124". Moving all index terms to the body (suggestion #3) would mean >each index target appears only with the first paragraph, after the title >and short description. There will be situations where the title and short >description are on the previous page, meaning we're back in the >"obviously bad" scenario of going to the wrong location. > >I started this note 90 minutes ago and now see one from Michael that >makes sense to me. 2 simple rules, based on the content we find (rather >than rules based on what we assume we will find). Quoting Michael, with >one (addition): >- if the topic title (or short description) mentions the subject, put the >index item in the prolog >- if it doesn't, put the index item as close to the subject matter as >possible > >Robert D Anderson >IBM Authoring Tools Development >Chief Architect, DITA Open Toolkit ( http://www.dita-ot.org/ ) > ><dita@lists.oasis-open.org> wrote on 07/08/2015 12:03:58: > >> From: Bob Thomas <bob.thomas@tagsmiths.com> >> To: Eliot Kimber <ekimber@contrext.com> >> Cc: Tom Magliery <tom.magliery@justsystems.com>, "Hudson, Scott" >> <scott.hudson@comtech-serv.com>, DITA TC <dita@lists.oasis-open.org> >> Date: 07/08/2015 12:04 >> Subject: Re: [dita] Index in the PDF version of the spec? >> Sent by: <dita@lists.oasis-open.org> >> >> Earlier I said: >> >> "Now, back to page numbering. If you restrict prolog index terms to >> those that correspond to the topic scope, there is never a case >> where the index will display an incorrect page number for such terms." >> >> I withdraw this claim. Here is why. Suppose you have a topic that >> covers branch filtering. The index term "conditional processing" >> would apply to the entire topic. However, the text in the topic does >> not mention conditional processing by name until the last half of >> the topic. We are still logically correct in associating the >> "conditional processing" with the topic, but the reader knows >> nothing about our notions of scope, and when the first mention of >> "conditional processing" falls a page other than where the topic >> began the reader perceives that we are incompetent. This is >> essentially the same thing that Eliot said earlier, but I was too >> anchored to the notion of using indexterm in prolog to understand it. >> >> I can think of three choices: 1) no index, 2) add the @start >> attribute to all leaf-node indexterms in the prolog, 3) abandon >> prolog/keywords/indexterm entirely and use inline markup only. >> >> Best Regards, >> Bob >> >> On Wed, Jul 8, 2015 at 8:55 AM, Bob Thomas <bob.thomas@tagsmiths.com> >>wrote: >> I also insist that fidelity between index-referenced content and >> page numbers is essential. Beyond that, I argue in this message that >> 1) prolog is the only appropriate place for index terms that pertain >> to an entire topic, and 2) prolog is inappropriate for index terms >> that do not pertain to the entire topic. >> >> First, I believe that prolog/keywords/indexterm is the only >> appropriate place for index terms that pertain to an entire topic. >> Semantically, this makes sense because of the prolog element's >> position in the topic structure. But, let's consider the >> alternative. Suppose that we never use prolog for index terms and >> restrict ourselves to using only inline index markup. In this >> scenario, index terms that apply to the entire topic would >> presumably appear at the first opportunity in the topic structure >> (in Xpath, this would be /topic/body/*[1] or one of its >> descendants). Such markup violates the semantic intent of the >> vocabulary because the index term's containing element constitutes >> an implicit scope, and that scope won't usually match the topic scope. >> >> Now, back to page numbering. If you restrict prolog index terms to >> those that correspond to the topic scope, there is never a case >> where the index will display an incorrect page number for such terms. >> >> Second, if you place index terms in prolog that do not pertain to >> the entire topic, then you will likely have page numbers in the >> index that do not correspond to the content's location in the >> output. I agree with Eliot's assessment about our audience (this is >> also why I have been such a prig about wording during the review >> cycle). Consequently, I would rather not have an Index if the page >> numbering is going to be wrong upon occasion. >> >> Best Regards, >> Bob >> >> On Wed, Jul 8, 2015 at 7:48 AM, Eliot Kimber <ekimber@contrext.com> >>wrote: >> I don't agree with this heuristic. >> >> I hate to be difficult about this, but our audience is by and large >> technical communicators, people who have specific knowledge of and >> expectations for indexes. Thus they are likely to be the most critical >> audience possible, short of the members of the International Brotherhood >> of Professional Indexers. >> >> If the page number reference does not take you to the page where the >>thing >> indexed occurs they will notice and wonder why *and blame DITA for the >> failure*. Not the indexers, not the PDF generation process, not the Open >> Toolkit, DITA. >> >> That's my concern. >> >> We already have a huge problem in the community with statements like >>"DITA >> produces crappy print output". Having the DITA governing body produce a >> print document with what appear to be bad indexing would only exacerbate >> the problem. >> >> Cheers, >> >> E. >> >> >> ---- >> Eliot Kimber, Owner >> Contrext, LLC >> http://contrext.com >> >> >> >> >> On 7/7/15, 2:13 PM, "Tom Magliery" <dita@lists.oasis-open.org on behalf >>of >> tom.magliery@justsystems.com> wrote: >> >> >Here's a proposed heuristic that I think might get close to everyone's >> >intuition here: >> > >> >An <indexterm> should occur inline if and only if the location to which >> >the reader is directed from the index will occur under a bolded >> >(sub)heading that is NOT the topic title. In that case the indexterm >> >should appear at the location of the nearest bolded subheading. >> > >> >I arrived at this idea after pondering Eliot's remark about users not >> >understanding/caring about incorrect page numbers. My thought is that >>the >> >reader will be tolerant enough to accept a jump to the nearest "title" >> >(section/topic/whatever) and scan the text from there. It's not until >>you >> >(the reader's) eye hits another bolded title-like item that you wonder >> >what the heck is wrong. >> > >> >mag >> > >> > >> >From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On >> >Behalf Of Hudson, Scott >> >Sent: Tuesday, July 07, 2015 11:59 AM >> >To: Bob Thomas; Eliot Kimber >> >Cc: DITA TC >> >Subject: Re: [dita] Index in the PDF version of the spec? >> > >> > >> > >> >I think it is useful to provide a quality index for the specification. >>As >> >such, I also agree with Bob below. I think prolog indexterms should >>apply >> >to the entire scope of the topic, while inlines should also be used >>when >> >necessary. Since a lot of the spec has been broken into smaller >> >components, I also hope it is true that we should be able to stick with >> >the prolog approach in general. I do not want to rule out using the >> >inline terms, though. >> > >> > >> > >> >Thanks and best regards, >> > >> > >> > >> >Scott Hudson >> > >> >Senior Consultant >> > >> >Comtech Services Inc. >> > >> >303-232-7586 >> > >> > >> > >> > >> > >> > >> > >> > >> >From: <dita@lists.oasis-open.org> on behalf of Bob Thomas >> >Date: Tuesday, July 7, 2015 at 8:31 AM >> >To: Eliot Kimber >> >Cc: DITA TC >> >Subject: Re: [dita] Index in the PDF version of the spec? >> > >> > >> > >> >An index can be one of the better ways of finding things without having >> >to take a drink out of the firehose that is search. >> > >> > >> >I agree with Eliot's position on inline vs. prolog. The only index >>terms >> >in the prolog should be those that correspond with the entire scope of >> >the topic. In general (i.e., not just the spec), writing shorter >>tightly >> >scoped topics increases the likelihood that index terms will be in the >> >prolog rather than inline. >> > >> > >> > >> >Best Regards, >> > >> >Bob >> > >> > >> > >> >On Tue, Jul 7, 2015 at 8:19 AM, Eliot Kimber <ekimber@contrext.com> >>wrote: >> >I agree that an index is important. >> > >> >But I also feel very strongly that if the index entries are not in >>line, >> >the index should not be produced in PDF, for the simple reason that it >> >will result in many page number references that are wrong (because they >> >will point to the start of the topic rather than the place where the >>term >> >actually occurs). >> > >> >Readers will not understand or care why the page number references are >> >wrong and will assume that either we did poor job of indexing or assume >> >that DITA's normal PDF production tools can't do indexing properly, >> >neither of which is the case. >> > >> >So while having an index is important, if we can't put the index >>entries >> >in the source at the point of occurrence of the terms indexed then we >> >should not produce the index for PDF. >> > >> >I know from painful experience how much work it is to put index entries >> >inline if you aren't doing it as you write. >> > >> >Cheers, >> > >> >Eliot >> >---- >> >Eliot Kimber, Owner >> >Contrext, LLC >> > http://contrext.com >> > >> > >> > >> > >> >On 7/7/15, 9:00 AM, "Kristen James Eberlein" >><dita@lists.oasis-open.org on >> >behalf of kris@eberleinconsulting.com> wrote: >> > >> >>Background: >> >> >> >>We removed the index from the 1.2 specification because it was of >> >>extremely low quality. Since then, Robert and I have been improving >>the >> >>indexing as we can (placing all <indexterm> elements in the prolog), >> >>although there still are many holes. >> >> >> >>We *can* index during the forthcoming 30-day review, and I have >>several >> >>folks who have volunteered to work together under rigid guidelines to >>do >> >>so. >> >> >> >>Shall we move forward with this? I'm old school; I firmly believe that >> >>an index is an important and necessary entry point to information, >>and I >> >>don't think that online search can replace it. >> >> >> >>Let's talk about this. I know that we have TC members who think that >>an >> >>index is unprofessional in PDF output unless the <indexterm> entries >>are >> >>placed in-text. >> >> >> >>-- >> >>Best, >> >>Kris >> >> >> >>Kristen James Eberlein >> >>Chair, OASIS DITA Technical Committee >> >>Principal consultant, Eberlein Consulting >> >>www.eberleinconsulting.com < http://www.eberleinconsulting.com > >> >>+1 919 682-2290 <tel:%2B1%20919%20682-2290>; kriseberlein (skype) >> >> >> >> >> >>--------------------------------------------------------------------- >> >>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 >> >> >> >> >> > >> > >> > >> >--------------------------------------------------------------------- >> >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 >> > >> > >> > >> > >> > >> > >> > >> > >> >-- >> >Bob Thomas >> >+1 720 201 8260 >> > >> >Skype: bob.thomas.colorado >> > >> >Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype >> > >> >Time zone: Mountain (GMT-7) >> > >> > >> > >> > >> >> -- >> Bob Thomas >> +1 720 201 8260 >> Skype: bob.thomas.colorado >> Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype >> Time zone: Mountain (GMT-7) >> >> [image removed] >> > >> >> -- >> Bob Thomas >> +1 720 201 8260 >> Skype: bob.thomas.colorado >> Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype >> Time zone: Mountain (GMT-7) >> >> [image removed]