Re: [dita] Index in the PDF version of the spec?

[Eliot Kimber <ekimber@contrext.com>]

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