Re: [DOCS] [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.

Anyway, bottom line is I'm not terribly excited about fixing just this
one place.  I think we need to decide whether we like the new more-verbose
output for links.  If we don't, we need to fix the markup rules to not do
that.  If we do, there are a lot of places that need adjustment to be less
duplicative, and we should try to be somewhat systematic about fixing
them.

            regards, tom lane