OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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)




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]