Re: DOCBOOK: Marking up task-based information

[Tobias Reif <tobiasreif at pinkjuice dot com>]

Steven Cogorno wrote:


> <!ELEMENT Task - - (Title, IndexTerm*, TaskAbstract?, 
>                      TaskPreReq?, Procedure, Example*, RelatedInfo*))>

> <task id="foo-123">
>    <title>To Notify Users When a Host or Agent Is Down</title>
>    <taskabstract>

1. needed?
I'm not yet experienced enough with DocBook itself and usage thereof [1] 
to say if the proposal addresses general unsatisfied needs.
But I find myself structuring documentation via prerequisites, tasks, 
etc, so it looks useful to me.

2. case
In the DTD snippet above, element names are camel case, but in the 
example tags are lower case; I thought that would be invalid in XML.
BTW: I prefer lowercase, and I think this is the better choice for 
DocBook element names.

3. naming
Stuff like
  taskprereq
is not very readable IMHO. Perhaps
  prerequisites
  abstract (instead of redundant taskabstract)
etc would be nicer to write and read.

Tobi

[1]
DocBook is a very large grammar, and I didn't yet write many large 
projects in DocBook, just some smaller ones; I didn't use all of the 
DocBook elements. I do have many months of experience transforming 
DocBook documents though, and I have experience with designing XML 
languages and processing them, and with other aspects of working with XML.

--
http://www.pinkjuice.com/