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.
74 messages in org.oasis-open.lists.docbookRe: [docbook] Add topic element to Do...
.pgp