Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtp (Exim 4.84_2)
	(envelope-from
 <pgsql-docs-owner+M9039=pgsql+2Ddocs=arkaria.postgresql.org@postgresql.org>)
	id 1cP00M-0001ef-Jy
	for pgsql-docs@arkaria.postgresql.org; Thu, 05 Jan 2017 04:50:22 +0000
Received: from localhost ([127.0.0.1] helo=postgresql.org)
	by malur.postgresql.org with smtp (Exim 4.84_2)
	(envelope-from
 <pgsql-docs-owner+M9039=pgsql+2Ddocs=arkaria.postgresql.org@postgresql.org>)
	id 1cP00L-0003xE-T9
	for pgsql-docs@arkaria.postgresql.org; Thu, 05 Jan 2017 04:50:21 +0000
Received: from makus.postgresql.org ([2001:4800:1501:1::229])
	by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256)
	(Exim 4.84_2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1cP00J-0003wn-TK; Thu, 05 Jan 2017 04:50:20 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256)
	(Exim 4.84_2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1cP00C-00027A-9p; Thu, 05 Jan 2017 04:50:18 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id v054oBH6025964;
	Wed, 4 Jan 2017 23:50:11 -0500
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Tatsuo Ishii <ishii@sraoss.co.jp>
cc: pgsql-docs@postgresql.org, pgsql-hackers@postgresql.org
Subject: Re: [HACKERS] Questionable tag usage
In-reply-to: <20170105.092557.1822243556008160851.t-ishii@sraoss.co.jp>
References: <20170105.092557.1822243556008160851.t-ishii@sraoss.co.jp>
Comments: In-reply-to Tatsuo Ishii <ishii@sraoss.co.jp>
	message dated "Thu, 05 Jan 2017 09:25:57 +0900"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <25962.1483591811.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable
Date: Wed, 04 Jan 2017 23:50:11 -0500
Message-ID: <25963.1483591811@sss.pgh.pa.us>
X-Pg-Spam-Score: -5.1 (-----)
List-Archive: <http://archives.postgresql.org/pgsql-docs>
List-Help: <mailto:majordomo@postgresql.org?body=help>
List-ID: <pgsql-docs.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@postgresql.org>
List-Post: <mailto:pgsql-docs@postgresql.org>
List-Subscribe: <mailto:majordomo@postgresql.org?body=sub%20pgsql-docs>
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-docs>
X-Mailing-List: pgsql-docs
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

Tatsuo Ishii <ishii@sraoss.co.jp> writes:
> In:
> https://www.postgresql.org/docs/devel/static/runtime-config-file-location=
s.html
> "Specifies the configuration file for Section 20.2, =1B$B!H=1B(BUser Name=
 Maps=1B$B!I=1B(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=3D"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=3D"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=3D"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=1B,Ai=1B=
(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


--=20
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs