On 2020-05-15 18:47, Bruce Momjian wrote:
On Fri, May 15, 2020 at 11:30:34AM -0400, Bruce Momjian wrote:
On Fri, May 15, 2020 at 11:06:58AM -0400, Tom Lane wrote:
Bruce Momjian <br...@momjian.us> writes:
Well, I would like both the SQL command references and the application
man pages to have xreflabel text.
I guess my point is that in the other several thousand pages of the docs,
we just use <xref linkend="sql-whatever"/> or <xref
linkend="app-whatever"/>, and it looks fine and works fine. Why are you
insisting on doing it differently in the release notes?
(I also have a vague memory that we used to use special xref labels for
SQL commands, and got rid of it. So this seems like undoing history
with no solid reasoning. That was with the previous doc toolchain of
course, but it's still the case that we don't seem to need this.)
I think I see it now. Our README.links says:
<xref>
use to get chapter/section number from the title of the target
--> link, or xreflabel if defined at the target, or refentrytitle if target
--> is a refentry; has no close tag
http://www.oasis-open.org/docbook/documentation/reference/html/xref.html
I was not aware that refentry can pull from refentrytitle. I just
tested it for pg_upgrade, and it worked fine. I will adjust the release
notes now to use them. Thanks.
Done. Thanks for the tips.
This doesn't seem right. By adding xreflabels you are changing the
appearance for all links pointing to the target, not only from the
release notes. For example, if you now do
see <xref linkend="vacuum-basics"/> and <xref linkend="autovacuum"/>
which are both sect2s in the same chapter, then you get a rendered text of
see Section 24.1.1 and autovacuum
which is bizarre.
If you want the link appearance to change only in the release notes,
then the right approach is to use the <link> tag, as was done before.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
