Re: Does anyone besides
Michael disagree?
Yes,
we discussed this at several earlier points and agreed that
an
indexterm within the prolog would be a pointwise index
reference
to the
beginning of the topic.
I'd be the last one to say this means we
can't revisit this, but
it's
certainly not just Michael espousing this view.
It is the TC's
status quo
decision.
paul
From: Dana Spradley
[mailto:]
Sent: Tuesday, 2006 August 15
16:07
To: Michael Priestley
Cc: Chris Wong;
; JoAnn Hackos; Grosso, Paul
Subject: Re:
[dita] Are indexterm ranges backwards incompatible?
Well I guess we do disagree, Michael.
As
JoAnn's best practices document says (emphasis mine):
Insert
index entries that refer to entire topics in the prolog element using
the <keywords> tag
(<prolog><metadata><keywords><indexterm>”word(s) to
be included in the
index”</indexterm></keywords></metadata></prolog>).
In this case, it makes sense to
make the default a page range covering the entire topic, if ranges are
employed at all.
Does anyone besides Michael disagree?
I can't
see how you could, if you respect the semantics of an indexterm that is meant
to apply to an entire topic: how could that be a point reference, if ranges
are allowed?
That's why I'm belaboring this point: I'm flabbergasted
there could be any principled support for the opposite
position.
--Dana
Michael Priestley wrote:
I believe I understood your
point, I just disagree with it.
You're assuming that if a reader introduces a range somewhere, they
must generally want ranges, or at least that's a good default assumption. I
don't see that as a reliable cue to authorial intent, since most indexes
with ranges will still have point indexing as well.
I would rather err on the side of existing behavior
both because I think it's right and because it's easier to understand the
change: we don't have indexterm behavior changing radically depending on the
presence or absence of other markup in the processing scenario (eg
including/excluding a single topic with range markup would change the
processing of the entire book).
Is there anyone else on the TC who wants to change the default range
behavior for indexterm? I'm concerned that we may be spending a lot of time
on a proposal with no second, while there are a list of other issues to get
through. Please correct me if I'm wrong.
Michael Priestley
IBM DITA Architect and
Classification Schema PDT Lead
http://dita.xml.org/blog/25
Dana Spradley <>
08/15/2006 03:41 PM
To
Michael
Priestley/Toronto/IBM@IBMCA
cc
Chris Wong <>,
,
JoAnn Hackos <>,
"Grosso, Paul" <>
Subject
Re: [dita] Are indexterm ranges
backwards incompatible?
Again, you misunderstand my point Michael: the mere
introduction of page ranges in an index where they weren't allowed before
changes the meaning of every single page reference in that
index.
Where before they could be pointing to extended discussions,
now they must be interpreted as pointing to brief mentions.
Thus
using even a single ranged indexterm breaks backwards compatibility for the
writer that uses it.
Michael Priestley
wrote:
Fair enough - not every
writer, just every writer who makes use of an index range somewhere in their
deliverable, or has content reused by someone else who makes use of an index
range somewhere.
So:
-
it breaks backwards compatibility for every context that uses index
ranges
- it
breaks best practices for indexing
Can we call this an interesting idea but not
appropriate for the spec and move on to the next issue?
Michael Priestley
IBM DITA
Architect and Classification Schema PDT Lead
http://dita.xml.org/blog/25
Dana Spradley
<>
08/15/2006 02:44 PM
To
Michael
Priestley/Toronto/IBM@IBMCA
cc
Chris Wong <>, , JoAnn Hackos <>, "Grosso, Paul" <>
Subject
Re: [dita] Are indexterm ranges
backwards incompatible?
that's not correct,
Michael - it only requires writers who wish to make use of ranged indexterms
elsewhere to rewrite their content
if they don't, no reworking is
required
Michael Priestley wrote:
If we follow your suggestion then we're
throwing a switch that requires every writer currently using indexterms in
prologs to rewrite their content to preserve their existing
behavior.
I
think it makes the most sense both from a new user perspective (per JoAnn's
indexing best practice points) and from an existing user perspective (per my
backwards compatibility points) to say that indexterms without ranges behave
exactly the same way tomorrow as they do today.
If a particular
project wants the behavior you describe, they can write their content that
way (ie with index range elements), or override processing to change the
default behavior (ie get range outputs from indexterm markup).
Michael Priestley
IBM DITA Architect and Classification Schema
PDT Lead
http://dita.xml.org/blog/25
Dana Spradley
<>
08/15/2006 02:17 PM
To
Chris Wong
<>
cc
JoAnn Hackos <>, "Grosso, Paul" <>,
Subject
Re: [dita] Are indexterm ranges
backwards incompatible?
What if we look at
this new feature as throwing a switch?
If a writer doesn't make use
of it, and refrains from inserting even one ranged indexterm into a book,
then they get 1.0 pointwise processing.
If, however, a user inserts
even one ranged indexterm into a book, then the ambiguity inherent in their
legacy indexterms is resolved as follows:
indexterms that appear in the body of the text are
considered pointwise. If they aren't, then the writer needs to insert new
start attributes and end elements into the body of the text.
indexterms that appear in topic metadata are considered
to apply to the topic as a whole, and as such generate a page range in the
index entry that corresponds to the page range of the topic. If the writer
doesn't like this, they need to go in and move the offending indexterms to
the most appropriate point in the body of the text.
Dana
Chris Wong wrote:
"A distinction is sometimes
made between continued discussion of a subject (index, for example, 34-36)
and individual references to the subject on a series of pages (34, 35, 36).
" -- 17.9, Chicago Manual of Style
I'd say that the difference between a
page range indexterm pair and a series of individual indexterms would make
that distinction. Never assume that the page references should be
combined.
I'd ask whether clarifying an ambiguity in the standard is
incompatible. If we strive to cater to every possible interpretation of any
ambiguity in the spec, we'd drive ourselves batty. I'm of the opinion that
our spec really says what the user can do and makes no attempt at a
comprehensive list of what a user cannot do. The latter would need an
inconveniently large truck to hold the resulting document. So if a user
writes DITA and expects processing behavior that the standard does not
expressively support, that user should not expect that nonstandard behavior
to be implemented by everyone. Indeed, expecting an unpromised feature of
DITA would easily lead to interoperability problems even within a
DITA version, let alone across versions.
As I see it, this is
probably not that big an issue because the XML itself will continue to be
valid, and the user can continue to use legacy processing. Such XML cannot
interoperate across DITA 1.0 implementations anyway.
Chris
From: JoAnn Hackos [mailto:]
Sent: Tuesday, August 15, 2006 1:47
PM
To: Grosso, Paul;
Subject: RE: [dita] Are indexterm ranges backwards
incompatible?
I would
not agree with the result assumptions. What mechanism exists for the numbers
5, 6, 7, and 8 to be concatenated into a range 5-8? A continuous
discussion ranging over pages 5-8 does not mean the same as points
referenced by the number 5, 6, 7, and 8. The indexer should be solely
responsible for determining when a range of pages is used, not have some
automatic decision made.
JoAnn
JoAnn T. Hackos, PhD
President
Comtech Services,
Inc.
710 Kipling Street, Suite 400
Denver, CO
80215
303-232-7586
joannhackos Skype
www.comtech-serv.com
From: Grosso, Paul
[mailto:]
Sent: Tuesday, August 15, 2006 11:21 AM
To:
Subject: RE: [dita] Are indexterm ranges backwards
incompatible?
I generally agree with Bruce here.
But I also need to take
issue with:
new
ranged indexterms they add would cause these old point indexterms to be
misinterpreted
With our existing indexterm markup, you cannot distinguish
between use of indexterms and ranges by looking at the resulting index. An
indexterm marks a point, and the page on which that point falls will be
included in the resulting index. An index range marks a start and end point,
and all pages starting with the one on which the start point falls and
ending with the one on which the end point falls will be included in the
resulting index.
Unless one has a fancier indexing process whereby one can, say,
request a bold page number in the index for the most important reference and
italic page numbers for pages on which there are related figures, etc.,
there is no distinction among page numbers in the resulting index.
Looking at the resulting index, one cannot tell if
index-page-range markup was used to create that index or not. A resulting
index entry of:
cheese 2, 5-8, 12
could have been generated by pointwise
indexterm markup throughout the source that just so happened to end up being
points on pages 2, 5, 6, 7, 8, and 12.
paul
From: Esrig, Bruce (Bruce)
[mailto:]
Sent: Tuesday, 2006 August 15 11:53
To: Dana
Spradley
Cc:
Subject: RE: [dita] Are indexterm ranges backwards
incompatible?
On the other hand, Dana,
This logic could be applied to outlaw any
extension, since every user would have to review every document to determine
whether they had intended to use the extension.
With DITA 1.1, we clarify
that an indexterm designates a point at which to start reading about the
indexed subject. The DITA 1.1 conceit is that this was true all along. In
DITA 1.0, this aspect of the interpretation was unspecified because there
was no way to specify anything else. But if it even makes sense to take
sides on this, it's possible to argue that the default disambiguation is the
DITA 1.1 way. Indexing practice typically presumes that an index entry
refers to a point at which to start reading.
For those who wish to
specify a range of pages possibly not starting at the top of a topic, a new
capability is provided that permits such a specification. The specification
of a range generates a page range in outputs that have page numbers, such as
PDF files. In other outputs, it generates a reference to the start page
only.
Best wishes,
Bruce Esrig
From: Dana Spradley
[mailto:]
Sent: Tuesday, August 15, 2006 12:41
PM
To:
Subject: [dita] Are indexterm ranges backwards
incompatible?
After
this morning's meeting, I'm starting to think that maybe ranged indexterm
should be considered backwards incompatible with DITA 1.0.
In 1.0, it
is ambiguous whether indexterms point to discussions confined to a single
page, or to extended discussions that begin on a certain
page.
Introducing ranged indexterms removes that
ambiguity.
Users who want to make use of ranged indexterms would need
to go back through their entire document set and replace current point
indexterms with ranged indexterms where appropriate - otherwise any new
ranged indexterms they add would cause these old point indexterms to be
misinterpreted.
Doesn't that amount to backwards
incompatibility?
--Dana
