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/
