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" < on behalf of > 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/ ) > ><> wrote on 07/08/2015 08:48:02: > >>
From: Eliot Kimber <> >>
To: Tom Magliery <>, "Hudson, Scott" >> <>, Bob Thomas <> >>
Cc: DITA TC <> >>
Date: 07/08/2015 08:48 >>
Subject: Re: [dita] Index in the PDF version of the spec? >> Sent by: <> >> >> 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" < on behalf >>of >> > 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: [ mailto: ] 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: <> 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 <> >>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" >>< on >>
>behalf of > 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 () 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 >> >
