Re: Questionable tag usage

On Thu, Jan 5, 2017 at 5:50 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Tatsuo Ishii <ishii(at)sraoss(dot)co(dot)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/