Re: [dita] Index in the PDF version of the spec?

[Michael Priestley <mpriestl@ca.ibm.com>]

Let me ask a different question - would
the following guidelines be acceptable?

- if the topic title mentions the subject,
put the index item in the prolog
- if it doesn't, put the index item
as close to the subject matter as possible 

Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/michael-priestley



From:      
 Michael Priestley/Toronto/IBM@IBMCA
To:      
 Bob Thomas <bob.thomas@tagsmiths.com>
Cc:      
 Eliot Kimber <ekimber@contrext.com>,
Tom Magliery <tom.magliery@justsystems.com>, "Hudson, Scott"
<scott.hudson@comtech-serv.com>, DITA TC <dita@lists.oasis-open.org>
Date:      
 07/08/2015 01:44 PM
Subject:    
   Re: [dita] Index
in the PDF version of the spec?
Sent by:    
   <dita@lists.oasis-open.org>

---

Do we have any actual cases where an
index term refers to a subject that is not represented in a heading (topic
level or section level)? 

Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/michael-priestley



From:        Bob
Thomas <bob.thomas@tagsmiths.com> 
To:        Eliot
Kimber <ekimber@contrext.com> 
Cc:        Tom
Magliery <tom.magliery@justsystems.com>, "Hudson, Scott"
<scott.hudson@comtech-serv.com>, DITA TC <dita@lists.oasis-open.org>
Date:        07/08/2015
01:04 PM 
Subject:        Re:
[dita] Index in the PDF version of the spec? 
Sent by:        <dita@lists.oasis-open.org>

---

Earlier I said: 

"Now, back to page numbering. If you restrict prolog index terms to
those that correspond to the topic scope, there is never a case where the
index will display an incorrect page number for such terms."

I withdraw this claim. Here is why. Suppose you have a topic that covers
branch filtering. The index term "conditional processing" would
apply to the entire topic. However, the text in the topic does not mention
conditional processing by name until the last half of the topic. We are
still logically correct in associating the "conditional processing"
with the topic, but the reader knows nothing about our notions of scope,
and when the first mention of "conditional processing" falls
a page other than where the topic began the reader perceives that we are
incompetent. This is essentially the same thing that Eliot said earlier,
but I was too anchored to the notion of using indexterm in prolog to understand
it. 

I can think of three choices: 1) no index, 2) add the @start attribute
to all leaf-node indexterms in the prolog, 3) abandon prolog/keywords/indexterm
entirely and use inline markup only. 

Best Regards, 
Bob 

On Wed, Jul 8, 2015 at 8:55 AM, Bob Thomas <bob.thomas@tagsmiths.com>
wrote: 
I also insist that fidelity between index-referenced content and page numbers
is essential. Beyond that, I argue in this message that 1) prolog is the
only appropriate place for index terms that pertain to an entire topic,
and 2) prolog is inappropriate for index terms that do not pertain to the
entire topic. 

First, I believe that prolog/keywords/indexterm is the only appropriate
place for index terms that pertain to an entire topic. Semantically, this
makes sense because of the prolog element's position in the topic structure.
But, let's consider the alternative. Suppose that we never use prolog for
index terms and restrict ourselves to using only inline index markup. In
this scenario, index terms that apply to the entire topic would presumably
appear at the first opportunity in the topic structure (in Xpath, this
would be /topic/body/*[1] or one of its descendants). Such markup violates
the semantic intent of the vocabulary because the index term's containing
element constitutes an implicit scope, and that scope won't usually match
the topic scope. 

Now, back to page numbering. If you restrict prolog index terms to those
that correspond to the topic scope, there is never a case where the index
will display an incorrect page number for such terms. 

Second, if you place index terms in prolog that do not pertain to the entire
topic, then you will likely have page numbers in the index that do not
correspond to the content's location in the output. I agree with Eliot's
assessment about our audience (this is also why I have been such a prig
about wording during the review cycle). Consequently, I would rather not
have an Index if the page numbering is going to be wrong upon occasion.

Best Regards, 
Bob 







On Wed, Jul 8, 2015 at 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)
>
>





-- 
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) 





-- 
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)