Re: [docbook] Add topic element to DocBook?

["Bob Stayton" <bobs@sagehill.net>]

----- Original Message ----- 
From: "Steven Cogorno" <Steven.Cogorno@Sun.COM>
To: "Michael Smith (tm)" <smith@sideshowbarker.net>
Cc: <docbook@lists.oasis-open.org>
Sent: Friday, October 27, 2006 10:21 AM
Subject: Re: [docbook] Add topic element to DocBook?


> Our documents are structured with conceptual and task based  
> information interspersed.  Here's an example:
> 
> 
> Troubleshooting Installation Issues     (chapter)
>    Initial Installation Issues          (sect1)
>       [introductory text here]
>       Disk-Related Issues               (sect2)
>       To Check IDE Disk for Bad Blocks  (task)
>       Using GRUB on X86 Platforms       (sect2)
>       To Use Live Upgrade with GRUB     (task)
>       [etc.]
> 
> The tasks and conceptual information related to that task are  
> presented together.  This is not possible in the current DocBook  
> implementation of Task.
> 
> In this particular example, the tasks could be contained within the  
> sect3.  But, that pushes the task based information (which our system  
> admins tell us is the most important content) down too deep in the  
> hierarchy.  This is also awkward for the reader because the document  
> ends up having section titles that serve only to satisfy the  
> structure, not to convey information.

But you could meet this need with <sect2 role="task">, couldn't you? 
While that may be less convenient for your authors than  an element
named <task>, I haven't been convinced that it is necessary to distort
the hierarchical structure of DocBook to accomodate this specialized need.

You could also easily customize DocBook to add a task (section) element
and remove the task (block) element.  Do you have requirements to
use only uncustomized DocBook?

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net