Re: Add topic element to DocBook?

[Norman Walsh <ndw@nwalsh.com>]

/ doug <doug.duboulay@gmail.com> was heard to say:
| the node useage. I guess there are semantic distinctions between 
| the topics and the sections.

The important semantic distinction, I think, between sections and
topics is that sections are (conceptually) sequential. First you read
section 1, then you read section 2, then you read section 2.1, etc.
Authors writing sections in this way can write with the expectation
that, when you're reading section 2.1, you've read all of section 1
and the introduction at the top of section 2. Phrases like "as we saw
in the preceding section" make perfect sense.

Topics, on the other hand, are discrete units. They stand alone.
There's no expectation that there's any particular topic "before" the
one you're looking at or "after" it. Typically there are hyperlinks
of various sorts to help you navigate the topics in the order that you
need to read them. You can't refer to "the previous topic" in any
sensible way.

Making a book of topics, something with sequential pages that's either
literally or virtually made out of dead trees, is an exercise in
choosing some sort of sequential order (hence the mapping/toc element)
for the topics.

There's nothing about the content model of <section>, or the content
models that it appears in, that makes it impossible to write modular
documentation with sections. But it carries conceptual baggage that
suggests a different style and of course it doesn't have the right
name for the pointy haired bosses of the world.

[ Coming back to doug's particular example ]

| If all the topics were sections, there would be little to distinguish
| what is currently the second section from what would be the the 
| third section (i.e. the first subtopic).

Hard technically, or hard conceptually? If it's hard technically, I'd
use a role attribute or something to mark the boundaries. If it's hard
conceptually, then, with respect, I'm not sure how changing the
element names helps. Readers, after all, don't see the element names.

|> Anyway, your example doc instance would not be valid according to
|> the proposed content model. By design.
|
| So close, and yet so far :-)

If we allow topics and sections to mix together, then I think we'll
have a confused mess that's very difficult to explain to users.
Several people have expressed concerns along these lines even in the
case where there's a clear distinction.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | There is a great difference
http://www.oasis-open.org/docbook/ | between seeking how to raise a
Chair, DocBook Technical Committee | laugh from everything, and seeking
                                   | in everything what may justly be
                                   | laughed at.--Lord Shaftesbury

PGP signature