Unfortunately,
there is no way for me to
indicate an index term that applies to the title of a topic, since
index term
is not allowed in title. I have to use the prolog instead to point to
the topic
title or short description. So the second bullet item below will not
work. I
don’t want to have to insert the index term in the first body
paragraph,
which might appear on a different page from the title.
I want to
use indexterm range elsewhere,
of course, and don’t want the behavior constrained in a manner that I
don’t
expect.
JoAnn
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, 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: [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
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,
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