When there is a long shortdesc and/or abstract and/or when
the style that the user has determined (remember, the DITA spec doesn't
prescribe style) has, say, the abstract start a new page.
By the way, indexterms are already allowed within titles by
wrapping them in a ph element.
paul
From: Dana Spradley
[mailto:]
Sent: Tuesday, 2006 August 15
14:46
To: Dana Spradley
Cc: JoAnn Hackos; Chris Wong;
Grosso, Paul;
Subject: Re: [dita] Are
indexterm ranges backwards incompatible?
Actually, I don't understand this
JoAnn.
When would a topic's title appear on a different page from the
first part of the body?
--Dana
Dana Spradley wrote:
wouldn't a cleaner solution to be to allow indexterms in
titles?
JoAnn Hackos wrote:
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
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: Dana
Spradley [mailto:]
Sent: Tuesday, August
15, 2006 12:18 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
