dita — archive

Index in the PDF version of the spec?

From: Eliot Kimber <[email protected]>
To: [email protected]
Date: Tue, 07 Jul 2015 19:15:00 -0000

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" <[email protected] on behalf of [email protected]> 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: <[email protected]> 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 ><[email protected]> 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" <[email protected] on >behalf of [email protected]> 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 ([email protected]) or Skype >Time zone: Mountain (GMT-7) > > > > > > > >