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> tag correctly.<para>" But the example-tutorial-en.xml contains the following snippet: <para> This is an example section. You can also use sect1, sect2, etc. </para> 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.)