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] FW: [Re: [xml-doc] DocBook 4.3 Task Markup]

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

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.


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 -----


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