dita — archive

Index in the PDF version of the spec?

From: Eliot Kimber <[email protected]>
To: [email protected]
Date: Wed, 08 Jul 2015 14:58:00 -0000

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