Ultimately XML is supposed to be about expressing
structure, not presentation. We don't have to make a decision in the TC about
how things look on paper.
We added page
range elements because it would be impossible for an index-generating
application to generate an index with ranges if they were not marked in the
input. But DITA 1.0 did not SAY whether indexes attached to topics should be
treated as points or ranges. If I were implementing a DITA printing engine a
year ago, I might have interpreted them as making a range because I agree with
Dana that that behaviour seems most useful.
After DITA 1.1, I will still have that choice.
In fact, this debate suggest to me that the choice should actually be in the
hands of the end-user. We could put some non-normative information in the spec
to that effect.
"Index terms in prologs are neither ranges nor points. They
are associated with the whole topic. DITA publishing implementations are
encouraged to let the end-user choose whether to represent them as page ranges
or individual pages in an index."
From: Dana Spradley
[mailto:]
Sent: Tuesday, August 15, 2006
11:45 AM
To: Michael Priestley
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
