Re: DOCBOOK: Bug at SGML DTD? Or at DSSSL stylesheets?

[Norman Walsh <ndw at nwalsh dot com>]

/ Jorge Godoy <godoy@conectiva.com> was heard to say:
| > There are three schools of thought on this issue:
| > 
| > 1. Figures (and other block-ish) things should appear in paras.
| > 2. Figures should not appear in paras.  
| > 3. Figures should appear in paras only if they are part of the
| >    paragraph from a semantic point  of view.
| > 
| > I tend to prefer 3 myself, but I've been authoring toward 2 most of
| > the time because HTML takes position 2.
| 
| Hmmmm... I prefer 2. I don't see how to make 3 work without mixing
| information... And 3 would also make positioning harder. 

I subscribe the view that the figure should be in the paragraph if
it's part of the narrative flow of the paragraph:

<para>In the following figure, note the red widget:
<figure><title>Blah, blah, blah</title>
...
</figure>
When you turn the handle to the left, you must move the widget out
of the way or you'll break the sprocket. Replacing the sprocket is
a difficult procedure that involves general anesthetic and a Tesla
Coil.</para>

This happens more frequently with examples and equations, perhaps, than
figures. If you don't want to have the figure in the paragraph, I think
it's important to rewrite the text. I think this is really ugly:

<para>In the following figure, note the red widget:</para>
<figure><title>Blah, blah, blah</title>
...
</figure>
<para>When you turn the handle to the left, you must move the widget out
of the way or you'll break the sprocket. Replacing the sprocket is
a difficult procedure that involves general anesthetic and a Tesla
Coil.</para>

The other advantage to putting the figure inside the paragraph is that
you can "pick it up" all at once with tools that allow GUI
manipulation of the document structure. Or point to it easily with a
single, non-spanning XPointer.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Where it is permissible both to
http://www.oasis-open.org/docbook/ | die and not to die, it is an abuse
Chair, DocBook Technical Committee | of valour to die.--Mencius