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 |
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 |