dita — archive

Index in the PDF version of the spec?

From: JoAnn Hackos <[email protected]>
To: [email protected]
Date: Wed, 08 Jul 2015 14:27:00 -0000

Definitely could provide a range of pages although it¹s better not to. JoAnn JoAnn T. Hackos, PhD President Comtech Services Inc. 710 Kipling Street, Suite 400 Denver, CO 80215 [email protected] 303-232-7586 We will be hosting the CIDM Online Conference on July 29, 2015 More information is available: https://forum.infomanagementcenter.com < https://forum.infomanagementcenter.com/ > On 7/8/15, 8:07 AM, "Hudson, Scott" <[email protected]> wrote: >Shouldn't an indexterm in the prolog be treated as an index range across >the entire topic when it is rendered? If not, then it sounds like >something in the processing that should be adjusted? > >-‹Scott > > > >On 7/8/15, 7:48 AM, "Eliot Kimber" <[email protected]> wrote: > >>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) >>> >>> >> >>