Re: [docbook] Add topic element to DocBook?

[Steven Cogorno <Steven.Cogorno@Sun.COM>]

On Oct 27, 2006, at 6:53 AM, Michael(tm) Smith wrote:
> Substitute the word "wary" for "afraid". The thing about changes
> is that they often have unforeseen consequences. For example, we
> decided to add Task as a child of section, and a year or two
> later, we've got to figure if/how to allow Task content in places
> where by design it's currently not permitted.


I'd like to add some clarification to the discussion about task.

On behalf of Sun Microsystems, I proposed the Task element.  We use  
Task extensively in our administration guides to encapsulate  
procedures along with the prerequisites and examples that are  
associated with that procedure.

In my proposal, Task was equivalent to a section.  Tasks are included  
in the TOC and tasks can be followed by other sections.  Basically,  
task was intended to be a section, but with the contents more  
strictly defined than section.

The TC discussed this over several meetings, and either I wasn't  
clear in my proposal, or it was interpreted differently than we had  
intended.  Task was implemented as a block, not a section level  
container.  Unfortunately, we did not notice this disconnect until  
after DocBook 4.4 was released and it was too late to change.


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.



> And I don't think there's any risk of DocBook stagnating. It's
> soundly designed and is meeting the needs of its target user base
> quite well.

On the whole, I agree with you, with one caveat.  DocBook is not  
currently meeting our needs for task based information.


Steven Cogorno
Sun Microsystems