Thread: [DOCS] Questionable tag usage
In: https://www.postgresql.org/docs/devel/static/runtime-config-file-locations.html --------------------------------------------------- ident_file (string) Specifies the configuration file for Section 20.2, “User Name Maps” user name mapping (customarily called pg_ident.conf).This parameter can only be set at server start. --------------------------------------------------- "Specifies the configuration file for Section 20.2, “User Name Maps” user name mapping" looks pretty strange to me because a raw section name appears. This is due to the corresponding SGML coding: <para> 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. </para> Shouldn't we use a link tag instead of the xref tag here? Attached is a patch to fix this. Best regards, -- Tatsuo Ishii SRA OSS, Inc. Japan English: http://www.sraoss.co.jp/index_en.php Japanese:http://www.sraoss.co.jp diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 30dd54c..1707d40 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -532,10 +532,10 @@ include_dir 'conf.d' </term> <listitem> <para> - 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. </para> </listitem> </varlistentry>
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
On Thu, Jan 5, 2017 at 5:50 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
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.
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 <magnus@hagander.net> writes:
> On Thu, Jan 5, 2017 at 5:50 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> 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
>> ...
>> 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é.
> 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.
PDFs do have hyperlinks, so that in itself isn't an argument for keeping
the dead-tree-friendly approach. However, I've noticed some variation
among tools in whether a PDF hyperlink is visibly distinct, or whether
you have to mouse over it to find out that it would take you somewhere.
Not sure if that's enough of a usability fail to argue for keeping the
old way.
regards, tom lane
On Fri, Jan 6, 2017 at 10:18 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: >> 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. > > PDFs do have hyperlinks, so that in itself isn't an argument for keeping > the dead-tree-friendly approach. However, I've noticed some variation > among tools in whether a PDF hyperlink is visibly distinct, or whether > you have to mouse over it to find out that it would take you somewhere. > Not sure if that's enough of a usability fail to argue for keeping the > old way. Personally, I wouldn't sweat it. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Robert Haas <robertmhaas@gmail.com> writes:
> On Fri, Jan 6, 2017 at 10:18 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>> 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.
>> PDFs do have hyperlinks, so that in itself isn't an argument for keeping
>> the dead-tree-friendly approach. However, I've noticed some variation
>> among tools in whether a PDF hyperlink is visibly distinct, or whether
>> you have to mouse over it to find out that it would take you somewhere.
>> Not sure if that's enough of a usability fail to argue for keeping the
>> old way.
> Personally, I wouldn't sweat it.
Um ... are you expressing an opinion on the question at hand (ie, whether
to continue using "see section m.n"-type cross-references), and if so
in which direction?
regards, tom lane
On Tue, Jan 10, 2017 at 9:58 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > whether to continue using "see section m.n"-type cross-references For my part, I have a preference for including the section name with the link text, although if it took much work to add it (rather than being the new default) I might question whether the benefit was worth the effort of adding it. -- Kevin Grittner EDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
On Tue, Jan 10, 2017 at 10:58 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Robert Haas <robertmhaas@gmail.com> writes: >> On Fri, Jan 6, 2017 at 10:18 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: >>>> 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. > >>> PDFs do have hyperlinks, so that in itself isn't an argument for keeping >>> the dead-tree-friendly approach. However, I've noticed some variation >>> among tools in whether a PDF hyperlink is visibly distinct, or whether >>> you have to mouse over it to find out that it would take you somewhere. >>> Not sure if that's enough of a usability fail to argue for keeping the >>> old way. > >> Personally, I wouldn't sweat it. > > Um ... are you expressing an opinion on the question at hand (ie, whether > to continue using "see section m.n"-type cross-references), and if so > in which direction? Not exactly. I'm saying that, in deciding that underlying question, we should assume that PDF readers will do something sensible with links. I think most do, and those that don't will presumably eventually be fixed so that they do. I might revise that opinion if several people show up and say "I use PDF reader X and it displays links in a dumb way and always will but I love it anyway", though. Personally, I think that if the doc toolchain changeover changed the way xrefs render - and it seems that it did - that's a bug that ought to be fixed, or the whole thing should be reverted. We have no agreement on that change, and a lot of existing markup that was written with the old way in mind. Or at least Peter ought to put some work into reviewing existing usages and cleaning up things that don't look right any more. I don't think "(see Section 10.20, Blah Blah)" is entirely horrible compared to "(see Section 10.20)" but there are lots of place that use other phrasing, like "This is further described in Section 10.20, which also explains how to frob your wug." and if those places now read "This is further described in Section 10.20, Using Wug Frobbing, which also explains how to frob your wug.", that's not so good. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Robert Haas <robertmhaas@gmail.com> writes:
> Personally, I think that if the doc toolchain changeover changed the
> way xrefs render - and it seems that it did - that's a bug that ought
> to be fixed,
I quite agree. We'll have enough to do with the toolchain changeover;
we don't need random changes in what common markup produces.
However, that complaint was already lodged in another thread. What I
think *this* thread is about is whether we ought to switch from the
up-to-now-project-standard style
... how to frob your wug (see <xref linkend="wug-frobbing">) ...
to
... how to <link linkend="wug-frobbing">frob your wug</link> ...
The second way is better adapted to modern doc-reading environments, IMO,
because it doesn't distract you with a parenthetical remark. But it loses
in output formats that don't have hyperlinks, or at least so I'd expect.
(Possibly an output format like that would insert footnotes, but I've
always found that a footnote marker every few words is really distracting
too.)
If we did start doing things this way, we wouldn't care so much what
<xref> produces because we wouldn't be using it anymore anyway.
Not that that's a good reason to accept the inconsistency.
regards, tom lane
On Tue, Jan 10, 2017 at 12:22 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > However, that complaint was already lodged in another thread. What I > think *this* thread is about is whether we ought to switch from the > up-to-now-project-standard style > > ... how to frob your wug (see <xref linkend="wug-frobbing">) ... > > to > > ... how to <link linkend="wug-frobbing">frob your wug</link> ... I'm not sure if what you describe as existing style is in fact standard practice. I say that because it's not really my practice. I tend to use <xref> if there is a way that I can incorporate the link text into the sentence without contortions or parentheses; if not, I use <link>. That's not exactly either of the styles you are mentioning here. It also means that it's quite likely that there are places where changing what xref produces will make the markup I committed produce not-so-nice output. I'd be included to write the above as something like: ...how to frob your wug, as further discussed in <xref linkend="web-frobbing">. > The second way is better adapted to modern doc-reading environments, IMO, > because it doesn't distract you with a parenthetical remark. But it loses > in output formats that don't have hyperlinks, or at least so I'd expect. I agree, but I think "working well in environments without hyperlinks" should be something close to a non-goal, perhaps even an anti-goal. If there's no loss from working well in such a format, fine; if there is, I'd rather cater to the 99.99% of people whose reading environment includes links rather than the other 0.01% of people. > (Possibly an output format like that would insert footnotes, but I've > always found that a footnote marker every few words is really distracting > too.) +1. > If we did start doing things this way, we wouldn't care so much what > <xref> produces because we wouldn't be using it anymore anyway. > Not that that's a good reason to accept the inconsistency. Since I've spent a fair amount of brainpower trying to use <xref> rather than <link> where possible, I'm not innately enthusiastic about a project whose end is to get rid of <xref>. I won't lose a lot of sleep over it if we decide to go that direction, though. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
On Tue, Jan 10, 2017 at 12:39:57PM -0500, Robert Haas wrote: > Since I've spent a fair amount of brainpower trying to use <xref> > rather than <link> where possible, I'm not innately enthusiastic about > a project whose end is to get rid of <xref>. I won't lose a lot of > sleep over it if we decide to go that direction, though. FYI, doc/src/sgml/README.links has instructions on how these markup elements behave, or at least used to behave. We need to update that file if it changed. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + As you are, so once was I. As I am, so you will be. + + Ancient Roman grave inscription +
On 1/4/17 11:50 PM, Tom Lane wrote: > 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. We can turn off the new link appearance and change it back to the old one. We had previously speculated that this change might be awkward in some cases, but without any concrete cases. If we have concrete cases, we can change it. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On 1/6/17 8:56 AM, Magnus Hagander wrote: > 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. And there are man pages as the canonical example of why environments without full hyperlinking are still useful. Also, I'm not fond of the style of writing where random words are hyperlinks, because then there is no context of what the link is for. Is it more information, is it the canonical definition, is a glossary entry, a link to Wikipedia, is it essential that I read the linked-to material to be able to understand the current material, etc. And for mostly technical reasons, the links sometimes point into the middle of a section, so it's hard to find what the link was supposed to help you with, even more so if the target section was rewritten since the link was placed. The xref style of linking makes the relationship between both ends of the link more explicit and keeps up with changes in either side of the link better. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On 1/4/17 19:25, Tatsuo Ishii wrote: > In: > https://www.postgresql.org/docs/devel/static/runtime-config-file-locations.html > > --------------------------------------------------- > ident_file (string) > > Specifies the configuration file for Section 20.2, “User Name Maps” user name mapping (customarily called pg_ident.conf).This parameter can only be set at server start. > --------------------------------------------------- > > "Specifies the configuration file for Section 20.2, “User Name Maps” > user name mapping" looks pretty strange to me because a raw section > name appears. This is due to the corresponding SGML coding: I have committed a fix for this. I have not found any more similar cases. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
> On 1/4/17 19:25, Tatsuo Ishii wrote: >> In: >> https://www.postgresql.org/docs/devel/static/runtime-config-file-locations.html >> >> --------------------------------------------------- >> ident_file (string) >> >> Specifies the configuration file for Section 20.2, “User Name Maps” user name mapping (customarily called pg_ident.conf).This parameter can only be set at server start. >> --------------------------------------------------- >> >> "Specifies the configuration file for Section 20.2, “User Name Maps” >> user name mapping" looks pretty strange to me because a raw section >> name appears. This is due to the corresponding SGML coding: > > I have committed a fix for this. > > I have not found any more similar cases. Thank you for fixing it. Best regards, -- Tatsuo Ishii SRA OSS, Inc. Japan English: http://www.sraoss.co.jp/index_en.php Japanese:http://www.sraoss.co.jp
On 1/11/17 11:55, Peter Eisentraut wrote: > On 1/4/17 11:50 PM, Tom Lane wrote: >> 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. > > We can turn off the new link appearance and change it back to the old > one. We had previously speculated that this change might be awkward in > some cases, but without any concrete cases. If we have concrete cases, > we can change it. This question is still open. Do we want to keep the new linking style Section 1.2.3, "Title", or revert back to the old style just Section 1.2.3? It's a simple toggle setting. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
>> On 1/4/17 11:50 PM, Tom Lane wrote:
>>> 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.
> This question is still open. Do we want to keep the new linking style
> Section 1.2.3, "Title", or revert back to the old style just Section
> 1.2.3? It's a simple toggle setting.
I'd vote for reverting for now. If someone wants to run through the
docs and make considered decisions about where the more verbose style
is a win and where it isn't, then we could make the style change.
But that does not seem like a high-priority task --- and at the moment,
what we've got is a huge pile of docs that were written with the
less verbose style of markup in mind. So my bet is that there's a lot
of places where more-verbose is not a win.
regards, tom lane
On 3/21/17 21:50, Peter Eisentraut wrote: > This question is still open. Do we want to keep the new linking style > Section 1.2.3, "Title", or revert back to the old style just Section > 1.2.3? It's a simple toggle setting. Changed back to old style, per discussion. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services