OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Re: DOCBOOK: Marking up task-based information


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/



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC