Yeah, it's definitely duplicative. It was less so before the recent docs-toolchain changeover, because in the old toolchain the <xref> tag only printed "Section M.N" and didn't include a section title; see the same page in prior versions. I'm sure the markup was written with that in mind. Not that that makes it good style necessarily. > Shouldn't we use a link tag instead of the xref tag here? Attached is > a patch to fix this.
- Specifies the configuration file for - <xref linkend="auth-username-maps"> user name mapping - (customarily called <filename>pg_ident.conf</>). - This parameter can only be set at server start. + Specifies the configuration file + for <link linkend="auth-username-maps">user name mapping</link> + (customarily called <filename>pg_ident.conf</>). This parameter can + only be set at server start.
Well ... that will read nicely in output formats that have hyperlinks, but not so well on plain dead trees where the cross-reference is either invisible or an explicit footnote. Our typical convention for this sort of thing has been more like "... file for user name mapping (see <xref linkend="auth-username-maps">)". That used to expand like
file for user name mapping (see Section 20.2).
and now it expands like
file for user name mapping (see Section 20.2, "User Name Mapping").
In either case the text after "see" is a hotlink if supported.
You could argue that nobody reads the PG docs on dead trees anymore and we should embrace the hyperlink style with enthusiasm. I wouldn't be against that personally, but there are a lot of places to change if we decide that parenthetical "(see Section M.N)" hotlinks are pass ,Ai (B.
I don't think there are a lto of people who use dead tree editions anymore, but they certainly do exist. A lot of people use the PDFs though, particularly for offline reading or loading them in ebook readers. So it still has to be workable there.
