On Thu, Jan 5, 2017 at 5:50 AM, Tom Lane <t...@sss.pgh.pa.us> wrote:

> Tatsuo Ishii <is...@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.

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.

 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Reply via email to