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
