Re: [docbook] Add topic element to DocBook?

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

On Oct 27, 2006, at 11:02 AM, Bob Stayton wrote:
>> 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.


That really didn't work well. We used to use role="procedure" to  
handle this, but it was very problematic.

Here's why:

* We couldn't restrict the content model based on the
   attribute and we ended up with very unreliable content.
   Example: a section might have the role="procedure" attribute
   but not have any steps.

* The components of a task couldn't be identified semantically.
   Many DocBook elements have semantic structures like MsgSet,
   QandASet, etc.  Task based information is a large percentage
   of our content, so we wanted to have well-defined structures.

* We couldn't do any sort of interesting processing with the
   task.  For example, expert users might not want to see the
   examples and prerequisites.  By having specific elements
   that identify this content, we can suppress content through
   profiling.

So, yes, we *could* use a section to contain task content.  But if we  
aren't going to benefit from structure, we might as well use  
orderedlist and dump task/procedure entirely.  We want the structure  
to model and shape the content.  The structure is important.



> 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?

This is what we've done, although, at the time, we didn't realize our  
implementation of Task was incompatible with DocBook.

We do significantly customize DocBook -- we call our DTD SolBook.   
However, one of our requirements is that our customizations remain a  
subset of what is permitted in DocBook.  We mostly remove elements,  
simplify content models, remove attributes, and add enumerated  
values.  Any document that parses with SolBook is expected to parse  
with DocBook.

Steven Cogorno
Sun Microsystems