Re: [docbook-apps] Question about <formalpara>

[Thomas Schraitle <tom_schr@web.de>]

Hi Daniel,

On Friday 27 January 2006 20:00, Daniel Carrera wrote:
>
> I'm trying to figure out how a <formalpara> should be displayed. The
> specification simply says that it's a paragraph with a title and is
> displayed "as a block". I'm not sure what it means by that though.
>
>    <formalpara>
>      <info>
>        <title>Some title</title>
>      </info>
>      <para>Some para</para>
>    </formalpara>
>
> Judging from one of the test files, it looks like the <title> is
> expected to stay with the paragraph. What else?

To my knowledge the current XSLT 1 stylesheets renders the title in bold 
plus a dot. The content from the para begins on the same line.


> Would you normally expect it to be indented more than a regular
> paragraph? Would you expect it to be on a frame with a border around
> it?

I think, it should be different from a sect{1,2,3,4}/title so nobody is 
confused by a formalpara/title.

From a typographical point of view, I would avoid borders as much as 
possible. They make sense, for example, for admonition boxes to get the 
attention from the reader. And maybe in headers or footers. But I don't 
think it would be a good idea to use it for this element. Think of a 
document that have to use lots of formalpara you end up with lots of line 
and this is a nightmare to read.

Indentation /can/ work but it is also a typographical minefield. Can you 
safely detect a formalpara/title if you have nested lists and other text 
that is indented too? Indentation can lead to a very disturbed left 
margin so the reader might be confused.

Why not use the DocBook rendering and display it in bold or as another 
option in italic? :-)


> I realize that these visual details are not meant to be part of the
> specification. But since I'm converting into OpenDocument, I want to
> represent it as something close to what most users would expect.

If I would use this stylesheets, I would expect that it behaves something 
similar to the DocBook output. It is probably a good idea to use 
parameters to adjust the output to user's needs. :)


> I tried to turn a sample file into PDF using the stylesheets that came
> with the DB distribution, but it didn't work well. For example, the
> <title> tag was ignored completely.

Which stylesheets did you use? There are two: for XSLT 1 and for XSLT 2. 
The latter is still in development and will probably replace the existing 
some day, but at the moment you should stick with the XSLT 1.
Your XML above looks like it is a DocBook 5 file. Try it with a DocBook 
4.x instance and use the XSLT 1 stylesheets instead.


Hope that helps,
Tom

-- 
Thomas Schraitle