Re: <xref> vs <command> formatting in the docs

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