FW: [Re: [xml-doc] DocBook 4.3 Task Markup]

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

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