Red Hat Bugzilla – Bug 125754
<para> usage in example-tutorial-en.xml conflicts with Docs Guide
Last modified: 2007-04-18 13:08:49 EDT
Description of problem:
The Documentation Guide says:
"Additionally, the <para> tags should be justified around the
paragraph so that the opening <para> tag and the first word of that
paragraph are side by side. For example:
<para>This paragraph talk about using the <para>
But the example-tutorial-en.xml contains the following snippet:
This is an example section. You can also use sect1, sect2, etc.
which contradicts what the Guide says.
Is there a reason why <para> tags have to be done in this way? I
find it easier to follow the markup (as an editor) when I see things
like the tutorial shows them. To me, the best possible situation would
be a single, uninterrupted "flow" of text that shifts indentation in
and out. I realize that the <screen> usage and a couple other
exceptions exist; not a problem.
More importantly, though, when one uses a block <para> it causes
Emacs/psgml to behave strangely when using M-q to fill. Maybe that's
bad Emacs usage; I'm an Emacs novice, so sue me. :-)
Above behavior resolved using sgml-fill-paragraph (C-c C-q), when the
DTD has been properly parsed (C-c C-p).
FWIW, the process specified in the Documentation Guide is legacy
information and doesn't (likely) apply to the XML.
I'll grab this bug to fix when I get CVS access.
It is legacy from the Documentation Guide we use for DocBook SGML. The
reason why this must be done is because having any space (carriage
return or blank spaces) after the <para> tag in DocBook SGML
causes a blank line in the PDF generated using DSSSL stylesheets. I
filed a bug on the DSSSL stylesheets for this but was told that it was
intended behavior and not a bug. So, to not get the blank line in the
PDF, we started this rule for <para> tags. I just tested it, and
it is not a problem with DocBook XML and XSL, so I am removing the
rule from the Docs Guide. (I never liked having to start the text
right after the tag either.)