Re: [HACKERS] Questionable tag usage

[Peter Eisentraut]

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


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

Re: [HACKERS] Questionable tag usage

[Tom Lane]

Peter Eisentraut  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


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

Re: [HACKERS] Questionable tag usage

[Peter Eisentraut]

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


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

Re: [HACKERS] Questionable tag usage

[Peter Eisentraut]

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


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

Re: [HACKERS] Questionable tag usage

[Peter Eisentraut]

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


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

Re: [DOCS] [HACKERS] Questionable tag usage

[Bruce Momjian]

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 
> rather than  where possible, I'm not innately enthusiastic about
> a project whose end is to get rid of .  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  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 +


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

Re: [DOCS] [HACKERS] Questionable tag usage

[Robert Haas]

On Tue, Jan 10, 2017 at 12:22 PM, Tom Lane  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 ) ...
>
> to
>
> ... how to frob your wug ...

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  if there is a way that I can incorporate the link
text into the sentence without contortions or parentheses; if not, I
use .  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 .

> 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
>  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 
rather than  where possible, I'm not innately enthusiastic about
a project whose end is to get rid of .  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


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

Re: [DOCS] [HACKERS] Questionable tag usage

[Tom Lane]

Robert Haas  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 ) ...

to

... how to frob your wug ...

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
 produces because we wouldn't be using it anymore anyway.
Not that that's a good reason to accept the inconsistency.

regards, tom lane


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

Re: [DOCS] [HACKERS] Questionable tag usage

[Robert Haas]

On Tue, Jan 10, 2017 at 10:58 AM, Tom Lane  wrote:
> Robert Haas  writes:
>> On Fri, Jan 6, 2017 at 10:18 AM, Tom Lane  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


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

Re: [DOCS] [HACKERS] Questionable tag usage

[Kevin Grittner]

On Tue, Jan 10, 2017 at 9:58 AM, Tom Lane  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


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

Re: [DOCS] [HACKERS] Questionable tag usage

[Tom Lane]

Robert Haas  writes:
> On Fri, Jan 6, 2017 at 10:18 AM, Tom Lane  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


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

Re: [DOCS] [HACKERS] Questionable tag usage

[Robert Haas]

On Fri, Jan 6, 2017 at 10:18 AM, Tom Lane  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


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

Re: [HACKERS] Questionable tag usage

[Tom Lane]

Magnus Hagander  writes:
> On Thu, Jan 5, 2017 at 5:50 AM, Tom Lane  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 > 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


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

Re: [HACKERS] Questionable tag usage

[Magnus Hagander]

On Thu, Jan 5, 2017 at 5:50 AM, Tom Lane  wrote:

> Tatsuo Ishii  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 
> 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
> -  user name mapping
> - (customarily called pg_ident.conf).
> - This parameter can only be set at server start.
> + Specifies the configuration file
> + for user name mapping
> + (customarily called 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  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/

Re: [HACKERS] Questionable tag usage

[Tom Lane]

Tatsuo Ishii  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 
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
-  user name mapping
- (customarily called pg_ident.conf).
- This parameter can only be set at server start.
+ Specifies the configuration file
+ for user name mapping
+ (customarily called 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 )".  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


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

[HACKERS] Questionable tag usage

[Tatsuo Ishii]

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:

   
 Specifies the configuration file for
  user name mapping
 (customarily called pg_ident.conf).
 This parameter can only be set at server start.
   

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'
   
   

- Specifies the configuration file for
-  user name mapping
- (customarily called pg_ident.conf).
- This parameter can only be set at server start.
+ Specifies the configuration file
+ for user name mapping
+ (customarily called pg_ident.conf).  This parameter can
+ only be set at server start.

   
  

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