Re: [docbook] Add topic element to DocBook?

["Michael(tm) Smith" <smith@sideshowbarker.net>]

doug <doug.duboulay@gmail.com>, 2006-10-27 17:17 +1000:

> > doug <doug.duboulay@gmail.com>, 2006-10-27 16:31 +1000:
> > >     <topic>
> > >       <section/>
> > >       <section/>
> > >       <topic>
> > >          <section/>
> > >          <section/>
> > >            <topic>
> > >              <section/>
> > >              <section/>
> > >            </topic>
> > >            <topic>
> > >               <section/>
> > >               <section/>
> > >            </topic>
> > >            ...
>
> Basically, from the point of view of publishing, it is preferable 
> to chunk on the datastructure nodes, i.e. the topics, rather than
> the sections, which may be things like descriptions and examples of
> the node useage. I guess there are semantic distinctions between 
> the topics and the sections.
> 
> 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).

Your example instance seems to me the best argument so far for why
we should not add a Topic element.

The current proposal is (I think) in part a response to an
existing request to allow Task as a sibling of Section. Which is a
bad idea. So the proposal could maybe be seen partly as a way to
avoid doing that while still meeting the fundamental requirement
behind that request. By design the current proposal doesn't allow
Topic as a sibling of Section (for the same reason Task is not
allowed as a sibling of Section). But it seems clear now that once
it is added, there will most likely be requests to allow it in
places that the current proposal doesn't permit. For example, as a
sibling and child of Section, as in your example.

I'm not saying that there's anything inherently wrong with that.
It's just that it would break DocBook. Or at least leave us with
something that goes against some fundamental design principles
underlying DocBook. And for what benefit? I've not seen a whole
lot of evidence to suggest that most current DocBook users have
need for the sort of modular authoring and content reuse that
having a Topic element might help to facilitate.

  --Mike

smime.p7s