From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
To: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
To: Alvaro Herrera <alvherre@2ndquadrant.com>
Cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: <xref> vs <command> formatting in the docs
Date: Fri, 25 Sep 2020 07:38:56 +0200
Message-ID: <e0786f80-f641-4330-cd7d-c309a68399e5@2ndquadrant.com> (raw)
In-Reply-To: <631ac57a-e4aa-a3a7-2b0d-0a84974c2205@2ndquadrant.com>
References: <20200621153038.GA2296@alvherre.pgsql>
<87lfkgnypi.fsf@wibble.ilmari.org>
<631ac57a-e4aa-a3a7-2b0d-0a84974c2205@2ndquadrant.com>
On 2020-07-10 17:05, Peter Eisentraut wrote:
> On 2020-06-21 18:57, Dagfinn Ilmari Mannsåker wrote:
>> Attached are two patches: the first adds the missing <application> tags,
>> the second adds <command> to all the SQL commands (specifically anything
>> with <manvolnum>7</manvolnum>).
>
> I have committed the first one.
>
> I have some concerns about the second one. If you look at the diff of
> the source of the man pages before and after, it creates a bit of a
> mess, even though the man pages look okay when rendered. I'll need to
> think about this a bit more.
I asked about this on a DocBook discussion list. While the general
answer is that you can do anything you want, it was clear that putting
markup into title elements requires more careful additional
customization and testing, and it's preferable to handle appearance
issues on the link source side. (See also us dialing back the number of
xreflabels recently.) This is also the direction that DocBook 5 appears
to be taking, where you can put linkend attributes into most inline
tags, so you could maybe do <command linkend="sql-select"/>. This
doesn't work for us yet, but the equivalent of that would be
<command><xref linkend="..."/></command>.
So, based on that, I think the patch proposed here is not the right one,
and we should instead be marking up the link sources appropriately.
(This also implies that the already committed 0001 patch should be
reverted.)
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
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-hackers@postgresql.org
Cc: peter.eisentraut@2ndquadrant.com, ilmari@ilmari.org, alvherre@2ndquadrant.com
Subject: Re: <xref> vs <command> formatting in the docs
In-Reply-To: <e0786f80-f641-4330-cd7d-c309a68399e5@2ndquadrant.com>
* 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