Larry,
Are you saying that the current presentation of formalpara is flawed in
that it does not make it clear that content following a formalpara is
not part of the formalpara?
David
________________________________
From: Rowland, Larry [mailto:[email protected]]
Sent: Friday, July 24, 2009 12:09 PM
To: David Cramer; [email protected]; Dave Pawson
Cc: [email protected]; Jirka Kosek; Scott Hudson
Subject: RE: [docbook] Why do formalparas only allow one para?
Kate,
There are actually usability reasons for the formalpara not
allowing multiple paras. If I have two paras in a formalpara immediately
followed by a para not associated with the two paras, how do I tell that
the third para is not part of the two-para formalpara? This is also why
DocBook does not allow paras to follow a section -- how do you tell the
section has ended.
I understand the frustration, and have dealt with the problem in
the past by using variablelists (as you described), by using lists
within the para for enumeration of the content items, and by redesigning
the content to use sections when appropriate, because they all provide a
method for the reader to determine that I have finished the formal
element. Part of designing solutions that circumvent DocBook's structure
is to make sure the reader can tell what the author intended, since the
reader frequently does not have access to the markup that shows the
containment relationship, and the format of the output is all that the
reader has available. The current render of a formalpara does not
provide any indication after the para that the formalpara has ended. If
you do modify the DTD, I would recommend adding some sort of obvious
marker following the last element of the formalpara to indicate it has
ended. The reason I say last element is that once you open up the
question of more than one para, you also have to deal with the question
of what else is legal inside the new thing you have created? How about
lists, figures, mediaobjects, and all the other block level elements?
I sympathize with the problem, since I have struggled with it in
the past, but please make sure the reader can tell what the writer
intended -- that has always been a goal in my development of transforms
and grammars that feed them. Coming up with new designs for markup is
pretty easy, making sure they can effectively communicate the author's
intent is much harder since the reader does not usually have access to
the markup, just a formatted page (or audio stream or whatever the
markup controls -- Markup, it's not just for text anymore!).
Best Regards,
Larry Rowland
________________________________
From: David Cramer [mailto:[email protected]]
Sent: Friday, July 24, 2009 9:51 AM
To: [email protected]; Dave Pawson
Cc: [email protected]; Jirka Kosek; Scott Hudson
Subject: RE: [docbook] Why do formalparas only allow one para?
Kate,
One option is to customize the DocBook DTD or schema. I happen
to have this handy because I did this already for our version of
DocBook. In this case, you'd create your own sybasebook.dtd variant of
the DocBook DTD containing the following:
<!ENTITY % docbook PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"path_to/4.5/docbookx.dtd">
%docbook;
<!ELEMENT formalpara (title, (%ndxterm.class;)*, para+ )>
<!-- End -->
The current DocBook xslts will probably render the formalparas
with multiple paras just fine, however you could also have a
preprocessing step that terms them back into legal DocBook formalparas
before passing the doc on to the DocBook xsls.
Longer term, you could submit an RFE or look at the topic
element that Scott mentioned (I'm not current on that discussion).
David
________________________________
From: [email protected]
[mailto:[email protected]]
Sent: Friday, July 24, 2009 8:17 AM
To: Dave Pawson
Cc: David Cramer; [email protected]; Jirka
Kosek; Scott Hudson
Subject: Re: [docbook] Why do formalparas only allow one
para?
What we need is a free-floating container element that
takes a title and allows other block elements (e.g, indexterms, paras,
lists, etc.,) within it.
We want a container element because it is useful for
reuse and relocation of content. We want the element to be free-floating
because we need to be able
to put the element anywhere and have other content
elements follow it (including itself).
The problem with bridgeheads is that they are just
titles and you can't show the relationship between the title and the
content that follows it. To xinclude you'd have
xinclude the bridgehead as well as each element that
follows. We would prefer to have one container element that you could
put an ID on and be able to conditionalize it and/or xinclude it.
We actually have two cases where we need free-floating
container elements with titles:
1) One where the title is not inline -- this element
would be akin to simplesect if simplesect was not non-floating.
2) One where the title is inline -- this element would
be akin to formalpara if formalpara allowed you to have more than one
para and allowed other block elements.
Currently for 1) we use sidebars instead of bridgeheads
because we needed a sub-section-level container element with a title,
that could be used anywhere and multiple times within a section.
Simplesect, because it is non-floating, did not meet our
requirements.
We are looking for a solution for 2) because formalparas
do not meet our needs, but they are the best alternative we have right
now.
Thanks again,
Kate
Dave Pawson <[email protected]>
07/24/2009 12:25 AM
To
David Cramer <[email protected]>
cc
Scott Hudson <[email protected]>,
[email protected], Jirka Kosek <[email protected]>,
[email protected]
Subject
Re: [docbook] Why do formalparas only allow one para?
Why not use a bridgehead and multiple paras?
formalpara is singular? Hence one para?
regards
--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk
