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?


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
Joann.hackos@comtech-serv.com
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" <scott.hudson@comtech-serv.com> 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" <ekimber@contrext.com> 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" <dita@lists.oasis-open.org on behalf
>>of
>>tom.magliery@justsystems.com> 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: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] 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: <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)
>>>
>>> 
>>
>>



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