On second thought, I agree that your proposal would solve
the technical issue. The term "article" confused me into thinking it was
primarily for authoring large, topic-containing documents.
But it will make your life as spec editor much harder (as
well as making the lives of readers harder). According to my understanding of
the proposal, we would have to go through the entire DITA spec and everywhere it
says "topic" (as in maps point to topics through "topicref" elements), we would
have to say: "topic or thingee" (depending on what we call the thingees). The
topicref attribute would be a misnomer because it could point to topics or
thingees. We'll have to add "thingee" to the "type" attribute. What module will
the shared elements be in? That seems like a lot of painful reworking to me. It
also implies that things with a certain organization are "topics" (even if they
nest deeply!) whereas things with a slightly different organization (even if
they have only one level of nesting) are not topics! They aren't articles. So I
don't know what to call them.
From: Michael Priestley
[mailto:]
Sent: Monday, November 07, 2005 10:27
AM
To: Paul Prescod
Cc:
Subject: RE: [dita] Two proposals for
nested sections
The proposal I made was
deliberately designed to support both cases.
I don't know how I can make my case for keeping topic
at its defined size any stronger. I know you believe it should be
company-specific, but DITA is designed to allow cross-company reuse, and part
of the tradeoff of adopting a standard is agreeing on some common units. If we
can't agree on the common units then we can't provide reuse. I'm willing
to define a new kind of unit to accomodate your needs, even though I disagree
with your design choices. But I'm not willing to conflate that new kind of
unit with topics, that have a more restrictive model that has already paid
large dividends for us.
Michael
Priestley
IBM DITA Architect
SWG Classification Schema PDT
Lead
"Paul Prescod"
<>
11/07/2005 12:53 PM
To
Michael
Priestley/Toronto/IBM@IBMCA
cc
<>
Subject
RE: [dita] Two
proposals for nested sections
I think that Erik Hennum had a good idea when he said that
there are two use cases:
1.
Creating content
objects that are large and deep.
2.
Providing
more flexibility for grouping elements in specialization (not larger content
objects but small objects with more precisely articulated
substructure).
Your proposal
seems designed primarily for the first case. I'm happy to have support for
that case but my immediately concern is more about the second one. I continue
to feel that DITA specializers should decide what is a "topic" based upon
their reuse analysis and not based on the rule that anything that contains
sections must be made a topic just because that's what the framework forces
them to do.
From: Michael Priestley
[mailto:]
Sent: Monday, November 07, 2005 8:24
AM
To: Paul Prescod
Cc:
Subject: Re: [dita] Two proposals for
nested sections
Paul,
Another alternative is to create an additional base
type at the same level as topic that allows nested divisions. That way we
don't affect the integrity of the topic architecture, but we give you the
ability to design content with nested subheadings within the overall DITA
architecture.
I'm thinking this would be conceptually
something like an article or whitepaper - longer than a topic, may contain
topics, but not in itself a topic. Note that we have been authoring articles
in DITA just using nested topics (there are examples in the toolkit), and that
will continue to be valid as well.
So:
<article id="xyz">
<title>A
longer piece of content</title>
<shortdesc>We still have the same general DITA structure of a title,
shortdesc, and body</shortdesc>
<articlebody>
<p>But we have one very important difference: instead of sections, we
have divisions, and we allow them to nest.</p>
<division>
<title>Divisions</title>
<p>Divisions have a
minimal structure consisting of an optional title followed by block-level
content. They are not addressable directly by maps in the way articles or
topics are, so in that respect they are more like sections, except that they
nest.</p>
<topic id="abc">
<title>Topics</title>
<body>
<p>We also allow topics to be authored inside the
body of the article, or pulled in via conref, so that articles can still
contain and reuse topics. So articles can still consume topics, even though
topics (being smaller) cannot consume articles.</p>
</body>
</topic>
</division>
</articlebody>
<related-links><link
href="somewhereelse.dita"/></related-links>
<article id="nestedarticle">
<title>A
subarticle</title>
<shortdesc>We could even allow articles to nest, after the
body - keeping articles separate from articles in the same way we keep topics
separate from topics, that is by separating their content into different
bodies.</shortdesc>
<articlebody><p>And so
on...</p></articlebody>
</article>
</article>
Michael Priestley
IBM DITA Architect
SWG Classification
Schema PDT Lead
"Paul Prescod"
<>
11/06/2005 08:51 PM
To
<>
cc
Subject
[dita] Two proposals
for nested sections
Since your concern is
preventing arbitrary nesting of narrative
documents, two solutions present
themselves:
1. Limit the nesting levels to some agreeable level that
is "enough
levels" to satisfy most customers wanting grouping and "not so
many
levels" as to support arbitrary narrative. This is truly a compromise
in
the sense that neither party walks away comfortable that their
concerns
are addressed in the general case. This can be easily achieved in
a DTD
with e.g. "subsection" and "subsubsection" elements.
2. Limit
the nesting in the out-of-box DITA using formally declared
constraints or
prose. In addition, provide a mechanism whereby a
knowledgable specializer
can loosen the constraint for their
specialization (not, typically, to
allow indefinite nesting, but rather
to allow the creation of grouping
elements in the specialization). The
specification can outline the dangers
of this loosening and the
situations under which we believe it is a good
thing. If we can agree
that these specializers are (in general)
knowledgable and trustworthy
then both parties achieve their
goal.
Paul Prescod
