RE: [docbook] Add topic element to DocBook?

["Rowland, Larry" <larry.rowland@hp.com>]

Aren't all of the DocBook elements you identified that have semantic
structures block elements?  I'm not sure I know of any that have the
ability to substitute into the hierarchy while carrying a semantic
structure.  Doesn't mean it can't be done, but it does mean changing the
model.

I really like the task element that was added to DocBook, since it does
exactly what you described -- provides a richer semantic environment for
grouping the information related to a procedure -- I have had to do the
same thing repeatedly in documenting products.  In terms of processing
prerequisites and such differently, couldn't the role or remap
attributes carry that type of instruction?

I guess I am concerned about processing expectations.  I want a task to
be visually distinct, which is easy when it is a block element.  Does a
sect2 equivalent task look like a sect3 equivalent task, or do the
headings take on the appearance of the equivalent of a section at the
same level in the hierarchy?  If so, haven't I lost the visual cue that
this is a task.

I guess I have been thinking of a task as a formal object, like a
procedure on steroids.

Larry Rowland 

-----Original Message-----
From: Steven.Cogorno@Sun.COM [mailto:Steven.Cogorno@Sun.COM] 
Sent: Friday, October 27, 2006 12:45 PM
To: Bob Stayton
Cc: Michael Smith (tm); docbook@lists.oasis-open.org
Subject: Re: [docbook] Add topic element to DocBook?


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



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org