OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] Are indexterm ranges backwards incompatible?



From an earlier note from JoAnn:
>The simplest method is to give the page number only for the first page of a longer item, letting the reader decide when he has had enough.

From earlier in this same thread:
>The indexer should be solely responsible for determining when a range of pages is used, not have some automatic decision made.

Apologies to JoAnn if her intent varies from what I'm quoting.

Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25



Dana Spradley <dana.spradley@oracle.com>

08/15/2006 05:06 PM

To
Michael Priestley/Toronto/IBM@IBMCA
cc
Chris Wong <cwong@idiominc.com>, dita@lists.oasis-open.org, JoAnn Hackos <joann.hackos@comtech-serv.com>, "Grosso, Paul" <pgrosso@ptc.com>
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

mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

Dana Spradley <dana.spradley@oracle.com>

08/15/2006 03:41 PM


To
Michael Priestley/Toronto/IBM@IBMCA
cc
Chris Wong <cwong@idiominc.com>, dita@lists.oasis-open.org, JoAnn Hackos <joann.hackos@comtech-serv.com>, "Grosso, Paul" <pgrosso@ptc.com>
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

mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
Dana Spradley <dana.spradley@oracle.com>

08/15/2006 02:44 PM


To
Michael Priestley/Toronto/IBM@IBMCA
cc
Chris Wong <cwong@idiominc.com>, dita@lists.oasis-open.org, JoAnn Hackos <joann.hackos@comtech-serv.com>, "Grosso, Paul" <pgrosso@ptc.com>
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

mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
Dana Spradley <dana.spradley@oracle.com>

08/15/2006 02:17 PM


To
Chris Wong <cwong@idiominc.com>
cc
JoAnn Hackos <joann.hackos@comtech-serv.com>, "Grosso, Paul" <pgrosso@ptc.com>, dita@lists.oasis-open.org
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:

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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]