pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedQuestionable tag usage
22+ messages / 8 participants
[nested] [flat]
* Questionable tag usage
@ 2017-01-04 23:40 Tatsuo Ishii <ishii@sraoss.co.jp>
0 siblings, 1 reply; 22+ messages in thread
From: Tatsuo Ishii @ 2017-01-04 23:40 UTC (permalink / raw)
To: pgsql-docs; +Cc: pgsql-hackrs@postgresql.org
In:
https://www.postgresql.org/docs/devel/static/runtime-config-file-locations.html
---------------------------------------------------
ident_file (string)
Specifies the configuration file for Section 20.2, $B!H(BUser Name Maps$B!I(B 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, $B!H(BUser Name Maps$B!I(B
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Attachments:
config.diff (text/x-patch, 767B) download
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>
* Questionable tag usage
@ 2017-01-05 00:25 Tatsuo Ishii <ishii@sraoss.co.jp>
0 siblings, 2 replies; 22+ messages in thread
From: Tatsuo Ishii @ 2017-01-05 00:25 UTC (permalink / raw)
To: pgsql-docs; +Cc: pgsql-hackers@postgresql.org
In:
https://www.postgresql.org/docs/devel/static/runtime-config-file-locations.html
---------------------------------------------------
ident_file (string)
Specifies the configuration file for Section 20.2, $B!H(BUser Name Maps$B!I(B 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, $B!H(BUser Name Maps$B!I(B
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Attachments:
config.diff (text/x-patch, 767B) download
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>
* Re: [HACKERS] Questionable tag usage
@ 2017-01-05 04:50 Tom Lane <tgl@sss.pgh.pa.us>
parent: Tatsuo Ishii <ishii@sraoss.co.jp>
1 sibling, 2 replies; 22+ messages in thread
From: Tom Lane @ 2017-01-05 04:50 UTC (permalink / raw)
To: Tatsuo Ishii <ishii@sraoss.co.jp>; +Cc: pgsql-docs; pgsql-hackers@postgresql.org
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Questionable tag usage
@ 2017-01-06 13:56 Magnus Hagander <magnus@hagander.net>
parent: Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 2 replies; 22+ messages in thread
From: Magnus Hagander @ 2017-01-06 13:56 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; PostgreSQL-development <pgsql-hackers@postgresql.org>
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
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-01-06 15:18 Tom Lane <tgl@sss.pgh.pa.us>
parent: Magnus Hagander <magnus@hagander.net>
1 sibling, 1 reply; 22+ messages in thread
From: Tom Lane @ 2017-01-06 15:18 UTC (permalink / raw)
To: Magnus Hagander <magnus@hagander.net>; +Cc: Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; PostgreSQL-development <pgsql-hackers@postgresql.org>
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-01-10 15:54 Robert Haas <robertmhaas@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 22+ messages in thread
From: Robert Haas @ 2017-01-10 15:54 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Magnus Hagander <magnus@hagander.net>; Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; PostgreSQL-development <pgsql-hackers@postgresql.org>
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-01-10 15:58 Tom Lane <tgl@sss.pgh.pa.us>
parent: Robert Haas <robertmhaas@gmail.com>
0 siblings, 2 replies; 22+ messages in thread
From: Tom Lane @ 2017-01-10 15:58 UTC (permalink / raw)
To: Robert Haas <robertmhaas@gmail.com>; +Cc: Magnus Hagander <magnus@hagander.net>; Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; PostgreSQL-development <pgsql-hackers@postgresql.org>
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-01-10 16:13 Kevin Grittner <kgrittn@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 0 replies; 22+ messages in thread
From: Kevin Grittner @ 2017-01-10 16:13 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Robert Haas <robertmhaas@gmail.com>; Magnus Hagander <magnus@hagander.net>; Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; PostgreSQL-development <pgsql-hackers@postgresql.org>
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-01-10 16:26 Robert Haas <robertmhaas@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 1 reply; 22+ messages in thread
From: Robert Haas @ 2017-01-10 16:26 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Magnus Hagander <magnus@hagander.net>; Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; PostgreSQL-development <pgsql-hackers@postgresql.org>
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [DOCS] Questionable tag usage
@ 2017-01-10 17:22 Tom Lane <tgl@sss.pgh.pa.us>
parent: Robert Haas <robertmhaas@gmail.com>
0 siblings, 1 reply; 22+ messages in thread
From: Tom Lane @ 2017-01-10 17:22 UTC (permalink / raw)
To: Robert Haas <robertmhaas@gmail.com>; +Cc: Peter Eisentraut <peter_e@gmx.net>; Magnus Hagander <magnus@hagander.net>; Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; PostgreSQL-development <pgsql-hackers@postgresql.org>
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
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-01-10 17:39 Robert Haas <robertmhaas@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 22+ messages in thread
From: Robert Haas @ 2017-01-10 17:39 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Peter Eisentraut <peter_e@gmx.net>; Magnus Hagander <magnus@hagander.net>; Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; PostgreSQL-development <pgsql-hackers@postgresql.org>
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-01-10 23:19 Bruce Momjian <bruce@momjian.us>
parent: Robert Haas <robertmhaas@gmail.com>
0 siblings, 0 replies; 22+ messages in thread
From: Bruce Momjian @ 2017-01-10 23:19 UTC (permalink / raw)
To: Robert Haas <robertmhaas@gmail.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; Peter Eisentraut <peter_e@gmx.net>; Magnus Hagander <magnus@hagander.net>; Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; PostgreSQL-development <pgsql-hackers@postgresql.org>
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 +
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Questionable tag usage
@ 2017-01-11 08:46 Jürgen Purtz <juergen@purtz.de>
parent: Tatsuo Ishii <ishii@sraoss.co.jp>
0 siblings, 1 reply; 22+ messages in thread
From: Jürgen Purtz @ 2017-01-11 08:46 UTC (permalink / raw)
To: pgsql-docs
Some general notes to the discussion about <xref> vs. <link> rendering
in the new toolchain:
(1) There is a general distinction in the *meaning* of the two elements:
<xref> is an internal link with validation semantic whereas <link> is an
external link to any URL. See:
http://doccookbook.sourceforge.net/html/en/dbc.markup.xref-vs-link.html
(2) The *rendering* of <xref> can be customized via its
xrefstyle-attribute. It switches numbering, title, page number, ... on
or off, see:
http://doccookbook.sourceforge.net/html/en/dbc.markup.xref.html#sec.markup.xref.xrefstyle
. This feature is available per element usage or as a default behaviour,
which is defined in the language file of the xslt process (eg: en.xml).
(3) The option to render the xref-output as described in (2) is
available since docbook 4.3. Unfortunately we use docbook 4.2. To
overcome this shortage we can use the following - more or less
cumbersome - workaround:
http://www.sagehill.net/docbookxsl/CustomXrefs.html#RoleNotXrefstyle and
http://www.sagehill.net/docbookxsl/CustomGentext.html .
Kind regards, Jürgen Purtz
On 05.01.2017 00:40, 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:
>
> <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
>
>
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-01-11 16:55 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 1 reply; 22+ messages in thread
From: Peter Eisentraut @ 2017-01-11 16:55 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; Tatsuo Ishii <ishii@sraoss.co.jp>; +Cc: pgsql-docs; pgsql-hackers@postgresql.org
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-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-01-11 17:02 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Magnus Hagander <magnus@hagander.net>
1 sibling, 0 replies; 22+ messages in thread
From: Peter Eisentraut @ 2017-01-11 17:02 UTC (permalink / raw)
To: Magnus Hagander <magnus@hagander.net>; Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; PostgreSQL-development <pgsql-hackers@postgresql.org>
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-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Questionable tag usage
@ 2017-01-12 15:50 Robert Haas <robertmhaas@gmail.com>
parent: Jürgen Purtz <juergen@purtz.de>
0 siblings, 1 reply; 22+ messages in thread
From: Robert Haas @ 2017-01-12 15:50 UTC (permalink / raw)
To: Jürgen Purtz <juergen@purtz.de>; +Cc: pgsql-docs
On Wed, Jan 11, 2017 at 3:46 AM, Jürgen Purtz <juergen@purtz.de> wrote:
> (1) There is a general distinction in the meaning of the two elements:
> <xref> is an internal link with validation semantic whereas <link> is an
> external link to any URL. See:
> http://doccookbook.sourceforge.net/html/en/dbc.markup.xref-vs-link.html
Eh, we use both <link> and <xref> for internal links and surely want
both to be validated. If that's no longer happening I don't think it
will be long before it bites us.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Questionable tag usage
@ 2017-01-12 16:09 Tom Lane <tgl@sss.pgh.pa.us>
parent: Robert Haas <robertmhaas@gmail.com>
0 siblings, 0 replies; 22+ messages in thread
From: Tom Lane @ 2017-01-12 16:09 UTC (permalink / raw)
To: Robert Haas <robertmhaas@gmail.com>; +Cc: Jürgen Purtz <juergen@purtz.de>; pgsql-docs
Robert Haas <robertmhaas@gmail.com> writes:
> On Wed, Jan 11, 2017 at 3:46 AM, Jürgen Purtz <juergen@purtz.de> wrote:
>> (1) There is a general distinction in the meaning of the two elements:
>> <xref> is an internal link with validation semantic whereas <link> is an
>> external link to any URL. See:
>> http://doccookbook.sourceforge.net/html/en/dbc.markup.xref-vs-link.html
> Eh, we use both <link> and <xref> for internal links and surely want
> both to be validated. If that's no longer happening I don't think it
> will be long before it bites us.
I think that is talking about something different, namely the difference
between linkend and href properties. linkend points to a tag in the
current document, and AFAIK it behaves the same in <link> or <xref>.
href is used for external links.
The author of the cited page may believe that <link linkend=...> is bad
style, but he doesn't say that in so many words, and even if he did
I'm not sure I would agree.
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-03-19 03:50 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Tatsuo Ishii <ishii@sraoss.co.jp>
1 sibling, 1 reply; 22+ messages in thread
From: Peter Eisentraut @ 2017-03-19 03:50 UTC (permalink / raw)
To: Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-03-19 10:18 Tatsuo Ishii <ishii@sraoss.co.jp>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 0 replies; 22+ messages in thread
From: Tatsuo Ishii @ 2017-03-19 10:18 UTC (permalink / raw)
To: peter.eisentraut@2ndquadrant.com; +Cc: pgsql-docs
> 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, $B!H(BUser Name Maps$B!I(B 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, $B!H(BUser Name Maps$B!I(B
>> 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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: Questionable tag usage
@ 2017-03-22 01:50 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 2 replies; 22+ messages in thread
From: Peter Eisentraut @ 2017-03-22 01:50 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; Tatsuo Ishii <ishii@sraoss.co.jp>; +Cc: pgsql-docs; pgsql-hackers@postgresql.org
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
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-03-22 03:02 Tom Lane <tgl@sss.pgh.pa.us>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
1 sibling, 0 replies; 22+ messages in thread
From: Tom Lane @ 2017-03-22 03:02 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: Tatsuo Ishii <ishii@sraoss.co.jp>; pgsql-docs; pgsql-hackers@postgresql.org
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
* Re: [HACKERS] Questionable tag usage
@ 2017-04-03 14:52 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
1 sibling, 0 replies; 22+ messages in thread
From: Peter Eisentraut @ 2017-04-03 14:52 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; Tatsuo Ishii <ishii@sraoss.co.jp>; +Cc: pgsql-docs; pgsql-hackers@postgresql.org
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-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
^ permalink raw reply [nested|flat] 22+ messages in thread
end of thread, other threads:[~2017-04-03 14:52 UTC | newest]
Thread overview: 22+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2017-01-04 23:40 Questionable tag usage Tatsuo Ishii <ishii@sraoss.co.jp>
2017-01-11 08:46 ` Jürgen Purtz <juergen@purtz.de>
2017-01-12 15:50 ` Robert Haas <robertmhaas@gmail.com>
2017-01-12 16:09 ` Tom Lane <tgl@sss.pgh.pa.us>
2017-01-05 00:25 Questionable tag usage Tatsuo Ishii <ishii@sraoss.co.jp>
2017-01-05 04:50 ` Tom Lane <tgl@sss.pgh.pa.us>
2017-01-06 13:56 ` Magnus Hagander <magnus@hagander.net>
2017-01-06 15:18 ` Tom Lane <tgl@sss.pgh.pa.us>
2017-01-10 15:54 ` Robert Haas <robertmhaas@gmail.com>
2017-01-10 15:58 ` Tom Lane <tgl@sss.pgh.pa.us>
2017-01-10 16:13 ` Kevin Grittner <kgrittn@gmail.com>
2017-01-10 16:26 ` Robert Haas <robertmhaas@gmail.com>
2017-01-10 17:22 ` Tom Lane <tgl@sss.pgh.pa.us>
2017-01-10 17:39 ` Robert Haas <robertmhaas@gmail.com>
2017-01-10 23:19 ` Bruce Momjian <bruce@momjian.us>
2017-01-11 17:02 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-01-11 16:55 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-03-22 01:50 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-03-22 03:02 ` Tom Lane <tgl@sss.pgh.pa.us>
2017-04-03 14:52 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-03-19 03:50 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2017-03-19 10:18 ` Tatsuo Ishii <ishii@sraoss.co.jp>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox