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


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

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

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

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,

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


"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

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