RE: [docbook-tc] task as sibling to section [was: DocBook Technical Committee Meeting Agenda: 18 October 2006]

["Gary Cornelius" <gary.cornelius@csw.co.uk>]

I also agree that task is a logical sibling.

 

For task modelling of applications the CCT Notation is an excellent reference and tree like. There is an XML description of the CTT Notation at  http://giove.isti.cnr.it/teresa/teresa_xml.html. I imagine that users will want to document information from the task models generated from tools like Teresa and that the demand for this will increase with a lot of recent innovations in tools used for task modelling and developing systems.

 

Kind Regards,

 

Gary

---

From: Nancy P Harrison [mailto:nancyph@us.ibm.com]
Sent: 17 October 2006 16:46
To: Grosso, Paul
Cc: DocBook Technical Committee
Subject: Re: [docbook-tc] task as sibling to section [was: DocBook Technical Committee Meeting Agenda: 18 October 2006]

I'm with Paul on this one. 
  

I don't think of <task> 
as something that is a logical sibling of <section> or <sect?>. 
 If we add this, do we also add <concept> as another sibling? 
 DocBook is a very effective implamentation of a particular model; it can 
be customized for other things, but despite the currently somewhat overwhelming 
number of elements, it generally models generic block elements, together with 
both generic and tech-specific inline elements.  The <refentry> and 
<reference> elements came out of a long-standing technical model also, and 
don't really correspond to the DITA 'reference' element.  (At least, I and 
others have had trouble adapting DITA 'reference' elements to the needs of 
standard refentry-type elements.) 

DocBook already has <procedure> as a block element that basically 
corresponds to the <steps> element inside a DITA <task>. The DocBook 
equivalent to a DITA <task> is probably a <section> - maybe with 
'class="task"' -  that  has nested items (nested <section> 
elements?) assigned to the roles of prerequisites, context, results, etc. as 
appropriate.   

DITA takes 
topics, and specializations of topics, as the basic interoperable items. 
 For DocBook, our users have typically used recursive <section> 
elements as the basic interoperable unit of informatin, when they needed to 
create extremely modular documentation.  I don't want to confuse the issue 
by adding another element that breaks the standard DocBook model for dealing 
with a need for modular content. 

just my $.02 

Nancy 


"Grosso, Paul" <pgrosso@ptc.com> wrote on 
10/17/2006 10:40:59 AM:

>  
> 
> > -----Original 
Message-----
> > From: Steven.Cogorno@Sun.COM 
[mailto:Steven.Cogorno@Sun.COM] 
> > Sent: Monday, 2006 October 16 
19:27
> > To: Grosso, Paul
> > Cc: DocBook Technical 
Committee
> > Subject: Re: [docbook-tc] DocBook Technical Committee 
Meeting 
> > Agenda: 18 October 2006
> > 
> > 
>> 9.  Unfinished business: RFE 1097183: Allow Task as a 
sibling
> > >> of sections
> > >
> > > 
I'm opposed to this.  Having multiple division-like
> > > 
things as siblings is a bad idea, and even if we have
> > > that in 
places now, I don't want to make things worse.
> > 
> > 
> > Can you elaborate why you think it's a bad idea?
> 
> 
1.  It complicates the DTD, making it harder for authors 
>   
  to understand how to mark up their documents.
> 
> 2. 
 It complicates the resulting instances, assuming
>     the 
authors have used such markup.
> 
> 3.  It breaks hierarchy, 
making things like numbering
>     sections difficult (do you 
number tasks and sections
>     as if they are the same kind of 
thing or not?).
> 
> 4.  It destroys the semantics of what it 
means to be a
>     section.
> 
> and probably more. 
 My 25 years of experience tells me
> it's the wrong thing to 
do.
> 
> > 
> > > If you want to use DITA, use DITA. 
 Let's not make a
> > > mess of DocBook.
> > 
> 
> 
> > That's not a productive answer.  Technical writing is 
quickly  
> > becoming very modular.  Whether we like it or 
not (personally, I'm  
> > not a fan), we have to address those 
needs if DocBook is to remain a  
> > relevant standard.
> 
> Well, I think it is a productive answer, but perhaps it's
> too 
much shorthand for you to appreciate.
> 
> For 20 years now, 
SGML/XML has had DTDs with the idea that
> the you use DTDs to model your 
data, and if you have different
> data and/or different processing needs, 
you make a different model.
> 
> CALS came along, and some product 
vendors (now mostly extinct)
> developed special applications that just 
worked with "the CALS
> DTD", but they missed the point of arbitrary 
DTDs.
> 
> Then HTML came along, and everyone started cramming all 
sorts
> of information into a single DTD, and when that didn't 
model
> what they wanted, they invented new tags or fooled with 
scripts.
> 
> A DTD should reflect the results of an information 
analysis for
> a given application or family of similar applications. 
 DocBook
> has done an excellent job of reflecting the 80/20 needs of 
the
> community it was designed to serve as well as optimizing the
> 
possibilities of allowing private extensions via parameter
> 
entities.
> 
> DITA has been developed based on a different 
information analysis
> for a different set of applications under different 
circumstances.
> 
> It makes no sense to look at DITA and try to 
incorporate all its
> elements into DocBook.  Trying to do so only 
ends up complicating
> a DTD that is already so complex it overwhelms 
beginning users
> and turns instances written to such a DTD into the 
equivalent
> of what we used to call spaghetti code back in my programming 
days.
> 
> paul