RFE 1097183 (Allow Task as a sibling of sections)

[Michael Smith <smith@xml-doc.org>]

For DocBook 4.3, Task was added to compound.class.
The content model of compound.class[1] looks like this:

  msgset|procedure|sidebar|qandaset|task
  %ebnf.block.hook;
  %local.compound.class;

  [1] http://docbook.org/tdg/en/html/pe-class-x.html#compound.class.parament

That's consistent with the "allow it to appear anywhere that
procedure appears now" rationale in the original proposal and with
the "sort-of floating container, like sidebar but more general"
thought that came up in early discussion about where to add it.

One consequence of that is that Task ends up being allowed as a
child of Procedure, along with being one of its parent elements.

  [2] http://docbook.org/tdg/en/html/procedure-x.html#d0e119067

And while that does allow Task to appear at the same levels in the
hierarchy as sections -- including as a child of Appendix, Article,
Chapter, Preface, Partintro, and Preface -- it does not allow it
to between sections, where Refentry is allowed.

For example, with Refentry, you can do something like the following:

  Chapter
    Sect1
    Refentry
    Sect1
      Sect2
      Sect2
      Refentry

That is, you can basically use Refentry in place of any section.
But you currently can't do that with Task.

So I'm wondering whether it might be more appropriate to add Task
to bookcomponent.content[3] and to all of the content models where
refentry.class[4] appears.

  [3] http://docbook.org/tdg/en/html/pe-content-x.html#bookcomponent.content.parament

The possible parent elements of bookcomponent.content are
Appendix, Article, Chapter, Preface, Partintro, and Preface, and
its content model looks like this:

  ((%divcomponent.mix;)+,
  (sect1*|(%refentry.class;)*|simplesect*|(%section.class;)*))
  | (sect1+|(%refentry.class;)+|simplesect+|(%section.class;

The possible parents of refentry.class are Reference, Sect1-5, and
Section.

  [4] http://docbook.org/tdg/en/html/pe-class-x.html#refentry.class.parament

Adding Task in those places would allow it to appear anywhere
that a section or a Refentry appears now. Given that what Task is
modeling is one of the three basic information categories --
conceptual, reference, and task -- used in technical
documentation, allowing Task to appear wherever the fundamental
DocBook reference-information container (Refentry) is allowed
seems like it might be appropriate.

  --Mike

Michael Smith <smith@xml-doc.org> writes:

> After looking at this a bit more, I realize it's not really a
> matter of treating Task like Sidebar at all. It's a matter of
> allowing it whererever Refentry is allowed within book components
> (Chapter, Preface, etc.) -- which is to say, wherever Section is
> allowed.
> 
> So we have a kind of precedent in we already have Refentry allowed
> wherever Section is allowed.
> 
> (If fact, Refentry is allowed in a place where Section isn't: as a
> _sibling_ to book components such a Chapter. Not that I'm saying
> we would want to allow that for Task...)
> 
> And for the sake of comparison, the DITA model (if I remember
> correctly), basically has three top-level elements: Concept,
> Reference, and Task (which are all "specializations" of the
> fundamental Topic element. I think).
> 
> So perhaps part of what we need to consider is whether the DocBook
> Task is a worthy hierarchical parallel to Refentry.
> 
>   --Mike
> 
> Michael Smith <smith@xml-doc.org> writes:
> 
> > I'm forwarding a reply I sent to a question that was posted to the
> > xml-doc list. Roger Shuttleworth, who posted the question, has
> > submitted RFE 1097183 for it -
> > 
> >   Allow Task as a sibling of sections
> >   http://sourceforge.net/tracker/index.php?func=detail&aid=1097183&group_id=21935&atid=384107
> > 
> > When the TC discussed Task back in January 2003, it seems like
> > there was some thought about allowing it to "float" like Sidebar
> > and so be a valid sibling of section elements.
> > 
> > But after that call, there's no record of any decision being made
> > not to allow that. But it ended up being added to DocBook 4.3 as a
> > non-floating element like other block elements.
> > 
> > Does anybody remember whether there was a consensus to make it
> > that way? If not, it seems like we should discuss it further and
> > decide whether that's really the way we want it.
> > 
> >   --Mike
> > 
> > ----- Forwarded message from Michael Smith <smith@xml-doc.org> -----
> > 
> > To: xml-doc@yahoogroups.com
> > User-Agent: Mutt/1.5.6i
> > From: Michael Smith <smith@xml-doc.org>
> > Date: Thu, 6 Jan 2005 13:45:32 +0900
> > Subject: Re: [xml-doc] DocBook 4.3 Task Markup
> > 
> > 
> > Roger Shuttleworth <rshuttleworth@activplant.com> writes:
> > 
> > > We are using structured FrameMaker and the DocBook 4.3 DTD. This version
> > > of DocBook includes Task markup, unlike previous versions, which suits
> > > us well as we have tried to separate conceptual information from
> > > procedural information.
> > 
> > [...]
> > 
> > > However, the 4.3 DTD does not allow a Task after a Sect2. It imposes the
> > > following order:
> > > Sect1
> > > 	Sect2 (conceptual)
> > > 		Task
> > > 		Task
> > > 	Sect2
> > > 		Task
> > > You cannot put a Task after a Sect2 as a sibling.
> > > 
> > > This mandates that all conceptual information be given first, followed
> > > by a series of tasks or procedures. No doubt there are very good reasons
> > > for this, but it would be good to have them articulated. Does this
> > > structure apply more to some types of technical material (e.g.
> > > maintenance guides) than others? I am quite willing to be told that this
> > > is the best way...
> > 
> > The only record I can find of discussion related to whether not to
> > allow Task as a sibling of sections is in the January 2003 TC
> > meeting minutes:
> > 
> >   http://lists.oasis-open.org/archives/docbook/200301/msg00130.html
> > 
> > Here's an excerpt from that discussion -
> > 
> >   Norm: It would be our first sort-of floating container. Like
> >   sidebar but more general.
> > 
> >   Steve: We look at this like a very special kind of section. The
> >   Task element can appear anywhere that a Sect2 or Sect3 can
> >   appear. We don't allow them at Sect4 or at the top of a chapter.
> >   They behave like any other kind of sections.
> > 
> >   Nancy: So they can't float inside para text. They have to be
> >   siblings to other sections.
> > 
> >   Steve: That's right. It's not like a figure or table, it works
> >   like a section.
> > 
> >   Nancy: So you could have a Sect3 and then a Task and then
> >   another Sect3.
> > 
> > But at some point between when that discussion and the time when
> > Task markup was added and released in Docbook 4.3, Task ended up
> > becoming a non-floating element like other non-section block
> > elements.
> > 
> > That may be because the TC explicitly intended for it to be that
> > way, but the decision didn't get recorded in meeting minutes. Or
> > it may instead just be an unintentional oversight.
> > 
> > Anyway, it seems like something the TC needs to discuss. Can you
> > please file a DocBook RFE requesting it? (That is, "Allow Task as a
> > sibling of sectioning elements" or however you want to word it.
> > 
> > The form is at:
> > 
> >   https://sourceforge.net/tracker/?func=add&group_id=21935&atid=384107
> > 
> > You'll need to have a Sourceforge account/username in order to
> > submit it.
> > 
> > If you don't want to hassle with that, I can submit it for you.
> > But it'd be much better if you did it yourself, and included as
> > much details as possible about your specific use case and
> > rationale for changing it.
> > 
> >   --Mike
> > 
> > ----- End forwarded message -----
> 
>

smime.p7s