Okay, I've had enough of this fruitless discussion
for today and tomorrow, and am letting my proposal stand for further
consideration until one of its opponents submits a counterproposal that
resolves the issues it was meant to resolve as well as, or hopefully
better than, I was able to.
In fact, I would propose this as a remedy for what has become a
dysfunctional TC process going forward:
- All criticisms of a TC member's proposal should be ignored,
unless the TC member making the criticism submits a counterproposal
that not only resolves the criticism made, but also resolves the
criticisms that prompted the original proposal as well as or better
than they were resolved before.
Kinda like the golden rule of standards
discussions: do unto others as you would have them do unto you.
Otherwise DITA is destined to remain a parochial IBM standard dominated
by whoever has the job of its chief architect, and so can spend more
time than the rest of us hashing things out - and all our TC
"consensus" decisions are doomed to unravel because they never truly
were consensus decisions in the first place.
--Dana
Michael Priestley wrote:
I'm not interested in revisiting
bookmap
for this. Is anyone besides Dana interested in reopening bookmap?
Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
I guess we could rephrase the markup as
a second-order metacommentary on the meaning of various kinds of
indexterms
- all optional elements in indexlist:
indextermEnd (meaningful | meaningless)
topicalIndexterm (meaningful | meaningless)
sequentialIndexterms (meaningful | meaningless)
If indextermEnd is deemed meaningful,
then
start/end elements generate a range - otherwise they don't.
If topicialIndexterm is deemed meaningful, then indexterms in topic
metadata
generate a range - otherwise they don't.
If sequentialIndexterms are deemed meaningful, then they generate a
range.
Otherwise they're left as points.
Or however a particular site wishes to implement the meaningfulness or
meaninglessness of these elements, as defined by the bookmap builder.
Everything worthy of dispute is a question of meaning in the end, after
all.
--Dana
Dana Spradley wrote:
In fact, one could say the ability to
deploy
markup to build a book at all is not a semantic use of markup, but
merely
a structural one.
So neither of you supports using markup to build books?
Dana Spradley wrote:
Also I take it that both of you would
like
to see indexlist and all other -list elements removed from the bookmap?
Their sole purpose is to determine implementation-specific behavior as
well.
--Dana
Dana Spradley wrote:
I think I'm suggesting that indexterms
with matching start and end attributes do not generate an index range
by
default.
That would be backwards incompatible with existing 1.0 markup.
If you object to using markup to define implementation behavior, then
you
should leave this choice to the stylesheet or other
implementation-specific
configuration too.
Otherwise you are in fact using indexterm start/end markup to define a
new implementation behavior already.
--Dana
Michael Priestley wrote:
I agree we should not be adding new markup for a tool decision,
although
we should document the intended behavior of the existing proposed
elements.
indexterm generates an index entry (no change from 1.0).
indexterms with matching start and end attributes generate an index
range
(new functionality for 1.1).
What is the current criteria for establishing a match between start and
end attributes?
- referencing syntax: simple tokens, or standard DITA references?
- valid scope: same document (eg same physical file), same topic or map
(eg same logical unit), same indexing pool type (eg index in map
matches
any index in map), or same deliverable (eg just has to match somewhere)?
Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
I'm opposed to adding markup to the DITA spec that defines
implementation
behavior.
The DITA spec is supposed to define markup semantics, not
presentational
results. That's what stylesheets and other implementation-specific
configuration
should do. If you want to suggest such options for the DITA toolkit,
take
it to the dita-ot-developer list, but such things do not belong in the
DITA standard.
paul
From: Dana Spradley [mailto:dana.spradley@oracle.com]
Sent: Wednesday, 2006 August 16 11:51
To: dita@lists.oasis-open.org
Subject: Re: [dita] Proposed index range revisions (was Re: [dita]
Are indexterm ranges backwards incompatible?)
explicit: turns on range rendering for explicitly ranged indexterms -
those
with corresponding start and end attributes
topic: turns on range rendering for topics indexed in their prolog, the
range being the page range of the topic itself, not including any
subtopics
sequences: turns on the transformation of continuous page sequences
into
page ranges
--Dana
Esrig, Bruce (Bruce) wrote:
It would help to have explicit behavior statements for the three
indicators:
explicit, topic, sequences.
Bruce
From: Dana Spradley [mailto:dana.spradley@oracle.com]
Sent: Wednesday, August 16, 2006 12:11 PM
To: dita@lists.oasis-open.org
Subject: [dita] Proposed index range revisions (was Re: [dita] Are
indexterm ranges backwards incompatible?)
Thanks for working up an initial proposal, Paul. I also like the
wording
- and for suggesting the path towards an inclusive compromise.
I've done some additional thinking overnight, however, and now offer a
more systematic approach to the issue.
Proposed changes to existing index range proposal:
1. Default behavior to remain
unchanged from 1.0. Even if you enter an explicit index range with
start
and end attributes, it will still be rendered as a point index
reference
to the start page by default.
2. Range rendering in all
identified cases to be turned on by a new optional element contained by
indexlist in the bookmap:
ranges (explicit?, topic?, sequences?)
Justifications:
1. Ensures backwards compatibility
with 1.0 during the time it takes to review all indexterms in your
document
set and change them to ranges where appropriate - a deliverable might
come
up while you're in the midst of the change, which is likely to be back
burner.
2. If you don't employ index
ranges and a partner does, allows you to easily eliminate the ranges
from
partner doc in your output.
3. Allows people migrating
book-oriented legacy doc into DITA to bring page ranges along
initially,
then leave them in but turn them off when the transition to a
topic-based,
minimalist mode of presentation is accomplished (thanks to lurker Scott
Prentice for identifying this need).
4. Meets JoAnn's most fundamental
criterion: The
indexer should
be solely responsible for determining when a range of pages is used,
not
have some automatic decision made. This gives
everyone complete control over what ranges do or do not appear in their
index.
5. Locates that control
in the DTD, making it most easily accessible to writers.
--Dana
Tony Self wrote:
Your wording seems to entirely agreeable, Paul. My only change would be
to clarify what we mean by "end-user". In this recent flurry
of messages, some confusion may have been caused by mid-identification
of the stake-holders. To me, the people involved are (broadly) the TC
members,
the tool vendors, the writers, and the readers. By "end-user",
I think you mean "writer" (the end-user of the DITA publishing
tool).
Tony Self
________________________________
From: Paul Prescod [mailto:paul.prescod@xmetal.com]
Sent: Wednesday, 16 August 2006 10:17 AM
To: Dana Spradley; Michael Priestley
Cc: Chris Wong; dita@lists.oasis-open.org;
JoAnn Hackos; Grosso, Paul
Subject: RE: [dita] Are indexterm ranges backwards incompatible?
I propose the following wording:
"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
spanning
an entire topic or individual pages in an index. Another choice that
publishing
implementations may wish to provide is whether to collapse multiple
continguous
page references into a single page range."
________________________________
From: Dana Spradley
[mailto:dana.spradley@oracle.com]
Sent: Tuesday,
August 15, 2006 5:05 PM
To: Michael Priestley
Cc: Chris Wong;
dita@lists.oasis-open.org;
JoAnn Hackos; Paul Prescod; Grosso, Paul
Subject: Re: [dita]
Are indexterm ranges backwards incompatible?
I think we're still
working up to one Michael.
Do you have a suggestion
for how the serious reservations I've expressed with the current state
of the proposal could not simply be suppressed, but acknowledged and
overcome?
The TC's process
seems to have become very win/lose, IMHO - or maybe it was always that
way.
--Dana
Michael Priestley
wrote:
Dana, do you have a concrete
proposal for a change to the DITA 1.1 specification?
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>
<mailto:dana.spradley@oracle.com>
08/15/2006 06:23 PM
To
Paul Prescod <paul.prescod@xmetal.com>
<mailto:paul.prescod@xmetal.com>
cc
Michael Priestley/Toronto/IBM@IBMCA, Chris Wong
<cwong@idiominc.com>
<mailto:cwong@idiominc.com>
, JoAnn Hackos <joann.hackos@comtech-serv.com>
<mailto:joann.hackos@comtech-serv.com>
, "Grosso, Paul" <pgrosso@ptc.com>
<mailto:pgrosso@ptc.com>
, dita@lists.oasis-open.org
Subject
Re: [dita] Are indexterm ranges backwards incompatible?
I could agree to this compromise,
provided the default behavior is as I've outlined.
Then we could do the right thing
semantically in the default - but any particular user organization
could
override it and behave as illogically as they like.
--Dana
Paul Prescod wrote:
I don't think we can mandate
it, but we can submit the feature request. Given that it is open
source,
it depends on someone to implement it. You or I could just do it. I
would
be surprised if anyone would reject such a benign patch (although the
default
behaviour might be controversial).
Can we agree to this compromise
rather than continuing with the argument?
________________________________
From: Dana Spradley [mailto:dana.spradley@oracle.com
<mailto:dana.spradley@oracle.com>
]
Sent: Tuesday, August 15, 2006
12:44 PM
To: Paul Prescod
Cc: Chris Wong; JoAnn Hackos;
Grosso, Paul; dita@lists.oasis-open.org
<mailto:dita@lists.oasis-open.org>
Subject: Re: [dita] Are indexterm
ranges backwards incompatible?
And I suppose the following switch
as well:
*
generate-page-ranges-for-ranged-indexterms:
Yes/no
I agree that with such switches
available, this issue would go away.
How do we mandate that they be
put in the official DITA toolkit?
--Dana
Paul Prescod wrote:
The fact that the distinction
is "sometimes made" suggests to me that this is another thing
to put in the hands of the end user to express however their tool
expresses
it. One can imagine options to the DITA toolkit (or other publishing
engine):
generate-page-ranges-for-index-entries-on-adjacent-pages:
Yes/no
generate-page-ranges-for-entire-topics:
Yes/no
________________________________
From: Chris Wong [mailto:cwong@idiominc.com
<mailto:cwong@idiominc.com>
]
Sent: Tuesday, August 15, 2006
11:04 AM
To: JoAnn Hackos; Grosso, Paul;
dita@lists.oasis-open.org
<mailto:dita@lists.oasis-open.org>
Subject: RE: [dita] Are indexterm
ranges backwards incompatible?
"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
|