XML man page rendering issue

From: Peter Eisentraut <peter_e(at)gmx(dot)net>
To: pgsql-docs <pgsql-docs(at)postgresql(dot)org>
Subject: XML man page rendering issue
Date: 2011-07-29 20:40:04
Message-ID: 1311972004.768.13.camel@vanquo.pezone.net
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

Since 9.0, we have been using the DocBook XSL tool chain to create the
man pages, so the following applies as of that version.

We typically have mark up like this:

<para>
<command>foo</command> does something.
</para>

Technically, there is a whitespace between <para> and <command>, so when
you render this, you get an extra whitespace before the word "foo".
This would not be a problem if it were just

<para>
foo does something.
</para>

In HTML, you don't see this, because the rendering of the HTML in the
browser strips the whitespace (I think). But in the man pages, this
shows up.

We are currently using a fix, by having

<xsl:strip-space elements="para"/>

in the stylesheet. But now I noticed that this has some other negative
effects in cases such as

<para>
Use the <acronym>SQL</acronym> <command>COPY</command> command.
</para>

which renders in the man page as

Use the SQLCOPY command.

To clarify the full effect of this, I have attached a diff between how
the man pages would look like with and without the xsl:strip-space
option. (The diff is from what we currently use to what it would look
like if we removed the xsl:strip-space setting.)

For the short term, the question is which setting should we release
with.

Longer term, the right answer is obviously to fix the markup, but I'm
not sure right now how much time that would take.

Attachment Content-Type Size
manpages.diff.gz application/x-gzip 23.2 KB

Browse pgsql-docs by date

  From Date Subject
Next Message Jaime Casanova 2011-08-02 04:53:25 Re: postgres-9.1beta3 typo: recommendable --> recommended
Previous Message Kevin Grittner 2011-07-29 14:50:25 Re: postgres-9.1beta3 typo: recommendable --> recommended