From: Peter Eisentraut <peter_e@gmx.net>
To: pgsql-docs <pgsql-docs@postgresql.org>
Subject: XML man page rendering issue
Date: Fri, 29 Jul 2011 23:40:04 +0300
Message-ID: <1311972004.768.13.camel@vanquo.pezone.net> (raw)
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.
Attachments:
manpages.diff.gz (application/x-gzip, 23.2K) download
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: peter_e@gmx.net
Subject: Re: XML man page rendering issue
In-Reply-To: <1311972004.768.13.camel@vanquo.pezone.net>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox