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?


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" <dita@lists.oasis-open.org on
behalf of robander@us.ibm.com> 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/)
>
><dita@lists.oasis-open.org> wrote on 07/08/2015 08:48:02:
>
>> From: Eliot Kimber <ekimber@contrext.com>
>> To: Tom Magliery <tom.magliery@justsystems.com>, "Hudson, Scott"
>> <scott.hudson@comtech-serv.com>, Bob Thomas <bob.thomas@tagsmiths.com>
>> Cc: DITA TC <dita@lists.oasis-open.org>
>> Date: 07/08/2015 08:48
>> Subject: Re: [dita] Index in the PDF version of the spec?
>> Sent by: <dita@lists.oasis-open.org>
>> 
>> 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)
>> >
>> > 
>> 
>> 
>> 
>> ---------------------------------------------------------------------
>> 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
>> 
>




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