Michael Priestley wrote:
>
> Physically putting three topics on the same Web page clearly puts them
> closer together, and that is one potential result of physically nesting.
> That said, the chunk attribute removes some of the distinction between
> physically nested and logically nested topics, since you can move from
> one to the other as part of output processing.
Hmm. Looking at the chunk attribute I think I see what you are getting
at: physically nested topics could be taken to have an implicit chunk
value that means "render as a single physical unit of access" (e.g., a
single Web page or help entry).
That seems reasonable with the following caveats:
- The chunk attribute (and the semantics of "chunking" in general) are
by the admission of the architecture spec underspecified, to the point
where there's not enough useful definition to actually allow any
reliable behavior. So we'd need to crisp up the semantics of chunk
before we could define this behavior.
- chunk= would need to be specifiable on topic directly so that you
could override the implied default behavior.
But I don't think I would object to having nested topics imply, by
default, that they are rendered as single "chunks"--I think that would
be consistent with both what most authors would expect and the
convenience factor of nesting topics in the first place. And it could be
overridden at the map level or (by adding chunk= to topic) at the topic
level.
> If a specializer wanted to create special tasks for "subtask" and
> "overview task" they could - it is entirely a choice of what work you
> want to do via the doctype and what work you want to do via authoring
> guidelines.
Of course--the question is whether it's reasonable and/or appropriate to
allow it all in a single topic.
> Re the purpose of section: You're right that the current spec does not
> require section headings to be non-unique, and I am talking of current
> usage practice within IBM rather than normative requirements. That said,
> if you're wondering why we have sections at all, given that nesting
> topics provides the same functionality, it's the existence of repeating
> headings like "Purpose" and "Syntax" that clearly are not topics in
> their own right but merely divisions of an existing topic.
Hmmm--I think this is the essence of our difference on this topic: you
say "that clearly are not topics" in this context but discount my same
assertion in other contexts. I could just as easily make the argument
that sections within reference sections should be subordinate topics
(but I wouldn't because I happen to agree with the design of reference
topics).
That is, there is an inconsistency here that reflects an inherent and
unavoidable fuziness about what is and isn't or should and shouldn't be
a topic or a section. My instinct, in a standard of DITA's generality,
is to err on the side of permissiveness.
Essentially I'm saying that it's hard to find clear evidence for a
consistently-applied design principle on when one should or shouldn't
use topics or sections based on the design of the three base
specializations. The question is does that reflect inconsistency in the
design (possibly reflecting its iterative and pragmatic development
history) or does it reflect a failure in the specification to explain
how there is in fact consistency?
It is the nature of document types developed over time to sometimes be
inconsistent, but in the context of a standard we have an obligation to
try to be as consistent with our understood principles as we can be. In
the case of section vs topic I think we need to do better.
> So I do get nervous when we talk about nesting sections and giving them
> unique titles - at that point I do think there is even more potential
> for confusion between topics and sections. I'd prefer to make them more
> distinct from one another, and thus easier to choose between.
Doh! I just realized what you're getting at--I hadn't realized that the
various subcomponents of taskbody are themselves derived from section
(it should have been obvious because there's nothing else they could be).
So OK, I understand your objection to section nesting and I agree (for
now I am conceding that, at least in general, section nesting is not
required, although I'm not convinced that disallowing it is the correct
thing to do from a standards standpoint).
Given that, then maybe the appropriate thing would be to allow multiple
steps elements and restore the option of giving them a title (since they
are themselves sections) or, perhaps, allowing multiples but disallowing
multiple occurrences of the same local element type, if we decide we
feel strongly about disallowing unique titles for sections.
Hmmm.
I'll also observe that procedural information tends to be the most
complex and sophisticated in technical documentation and, at least
relative to real requirements I've dealt with over the years, DITA 1.1
is not anywhere close to sufficient to satisfying those requirements, at
least at first blush (it may be that many of the requirements can be
satisfies by rethinking how the information is organized and presented).
I'm thinking, for example, of even simple things like being able to
group steps within a single procedure, for example to associate specific
admonitions with them or to label them as a group or to allow them to be
re-used as a single unit.
But that is all stuff we'll have to think about post 1.1 of course.
Cheers,
Eliot
--
W. Eliot Kimber
Professional Services
Innodata Isogen
8500 N. Mopac, Suite 402
Austin, TX 78759
(214) 954-5198
ekimber@innodata-isogen.com
www.innodata-isogen.com