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
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
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:joann.hackos@comtech-serv.com]
Sent: Tuesday, August 15, 2006 1:47 PM
To: Grosso, Paul; dita@lists.oasis-open.org
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
joann.hackos@comtech-serv.com
joannhackos Skype
www.comtech-serv.com
From: Grosso, Paul [mailto:pgrosso@ptc.com]
Sent: Tuesday, August 15, 2006 11:21 AM
To: dita@lists.oasis-open.org
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:esrig@lucent.com]
Sent: Tuesday, 2006 August 15 11:53
To: Dana Spradley
Cc: dita@lists.oasis-open.org
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:dana.spradley@oracle.com]
Sent: Tuesday, August 15, 2006 12:41 PM
To: dita@lists.oasis-open.org
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
|