Re: [HACKERS] Questionable tag usage

Tatsuo Ishii <ishii@sraoss.co.jp> writes:
> In:
> https://www.postgresql.org/docs/devel/static/runtime-config-file-locations.html
> "Specifies the configuration file for Section 20.2,  $B!H (BUser Name Maps $B!I (B
> user name mapping" looks pretty strange to me because a raw section
> name appears.

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.

I complained previously that this seems a bit duplicative now,
but didn't get any responses:
https://www.postgresql.org/message-id/31278.1479587695%40sss.pgh.pa.us

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.