pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedFormatting of warning about using ident
7+ messages / 4 participants
[nested] [flat]
* Formatting of warning about using ident
@ 2019-06-14 08:47 Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 7+ messages in thread
From: Daniel Gustafsson @ 2019-06-14 08:47 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
The warning about using ident for authorization or access control is using a
<blockquote> with an <attribution> rather than a <warning>, making it look
quite different from the rest of the manual, and less like a warning IMO.
https://www.postgresql.org/docs/devel/auth-ident.html
The attached turns it into a <warning> and removes the <attribution> (this was
the sole place used in the docs) to make the docs more consistent for
formatting of warnings.
cheers ./daniel
Attachments:
ident_warning.patch (application/octet-stream, 1.3K) download
From 4f7c38b5cf07817883d7bafc0e51ca24d1594103 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Fri, 14 Jun 2019 10:29:59 +0200
Subject: [PATCH] doc: Turn ident warning into an actual <warning>
The warning about using ident for authorization or access control was
never turned into a warning, and was the last user of the <attribution>
tag. Turn into a <warning> to make the docs more consistent.
---
doc/src/sgml/client-auth.sgml | 7 +++----
1 file changed, 3 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index ffed887ab7..378115dec4 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1427,14 +1427,13 @@ omicron bryanh guest1
machine is under tight control and where the database and system
administrators operate in close contact. In other words, you must
trust the machine running the ident server.
- Heed the warning:
- <blockquote>
- <attribution>RFC 1413</attribution>
+
+ <warning>
<para>
The Identification Protocol is not intended as an authorization
or access control protocol.
</para>
- </blockquote>
+ </warning>
</para>
<para>
--
2.14.1.145.gb3622a4ee
=
* Re: Formatting of warning about using ident
@ 2019-06-26 13:09 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 7+ messages in thread
From: Peter Eisentraut @ 2019-06-26 13:09 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org
On 2019-06-14 10:47, Daniel Gustafsson wrote:
> The warning about using ident for authorization or access control is using a
> <blockquote> with an <attribution> rather than a <warning>, making it look
> quite different from the rest of the manual, and less like a warning IMO.
But this is a quote from the RFC. If you want to change it to a warning
box, then you also need to rephrase the surrounding text. But I don't
really see the need. It seems fine as it is.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Formatting of warning about using ident
@ 2019-07-01 11:48 Daniel Gustafsson <daniel@yesql.se>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 7+ messages in thread
From: Daniel Gustafsson @ 2019-07-01 11:48 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs@lists.postgresql.org
> On 26 Jun 2019, at 15:09, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
>
> On 2019-06-14 10:47, Daniel Gustafsson wrote:
>> The warning about using ident for authorization or access control is using a
>> <blockquote> with an <attribution> rather than a <warning>, making it look
>> quite different from the rest of the manual, and less like a warning IMO.
>
> But this is a quote from the RFC. If you want to change it to a warning
> box, then you also need to rephrase the surrounding text. But I don't
> really see the need. It seems fine as it is.
It is indeed a quote, but to my reading/understanding the only reason we’ve
included it is to act as a warning? Thats why the formatting stood out as it’s
not consistent for warnings. The attached v2 instead wraps the quote in a
<warning> with a slight rewording to make it even more prominent.
cheers ./daniel
Attachments:
ident_warning-v2.patch (application/octet-stream, 1.8K) download
From 3451bebdb293e60a097f45c05aa1cc486d475b2d Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Mon, 1 Jul 2019 13:45:12 +0200
Subject: [PATCH] Turn ident warning into an actual <warning>
The warning about using ident for authorization or access control was
not formatted as a <warning>, making it less visible for readers used
to the PostgreSQL documentation style. Wrap the quote in a <warning>
block with slight rewording to emphasize the warning.
---
doc/src/sgml/client-auth.sgml | 21 ++++++++++++---------
1 file changed, 12 insertions(+), 9 deletions(-)
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index ffed887ab7..bf7a70ee70 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1426,15 +1426,18 @@ omicron bryanh guest1
therefore only appropriate for closed networks where each client
machine is under tight control and where the database and system
administrators operate in close contact. In other words, you must
- trust the machine running the ident server.
- Heed the warning:
- <blockquote>
- <attribution>RFC 1413</attribution>
- <para>
- The Identification Protocol is not intended as an authorization
- or access control protocol.
- </para>
- </blockquote>
+ trust the machine running the ident server. RFC 1413 explicitly
+ warns about using ident authentication for authorization or access
+ control:
+ <warning>
+ <blockquote>
+ <attribution>RFC 1413</attribution>
+ <para>
+ The Identification Protocol is not intended as an authorization
+ or access control protocol.
+ </para>
+ </blockquote>
+ </warning>
</para>
<para>
--
2.14.1.145.gb3622a4ee
=
* Re: Formatting of warning about using ident
@ 2019-07-22 12:23 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 2 replies; 7+ messages in thread
From: Peter Eisentraut @ 2019-07-22 12:23 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
On 2019-07-01 13:48, Daniel Gustafsson wrote:
>> On 26 Jun 2019, at 15:09, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
>>
>> On 2019-06-14 10:47, Daniel Gustafsson wrote:
>>> The warning about using ident for authorization or access control is using a
>>> <blockquote> with an <attribution> rather than a <warning>, making it look
>>> quite different from the rest of the manual, and less like a warning IMO.
>>
>> But this is a quote from the RFC. If you want to change it to a warning
>> box, then you also need to rephrase the surrounding text. But I don't
>> really see the need. It seems fine as it is.
>
> It is indeed a quote, but to my reading/understanding the only reason we’ve
> included it is to act as a warning? Thats why the formatting stood out as it’s
> not consistent for warnings. The attached v2 instead wraps the quote in a
> <warning> with a slight rewording to make it even more prominent.
Being a quote and being a warning are two orthogonal properties. So in
that sense, wrapping the quote in a warning element is more correct.
But the problem is now that a warning box is meant to be formatted out
of line, so writing something like
<para>This feature does this and that and the other, but
<warning>
You can really make a mess with this.
</warning>
</para>
is not correct. (I'm surprised the schema even allows this.) If you
want to do this, you need to rewrite the surrounding text to be
independent of the warning and rewrite the warning to be outside of the
para and independent of it. I don't think that would be an improvement
though.
In general, I would argue in favor of fewer "note", "warning", etc.
Some documentation pages are now just a sequence of "note"s and little
proper text. If the normal text properly explains a topic and its pros
and cons, then we don't need all that extra decoration and it makes the
text easier to read.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Formatting of warning about using ident
@ 2019-07-22 14:09 Tom Lane <tgl@sss.pgh.pa.us>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
1 sibling, 1 reply; 7+ messages in thread
From: Tom Lane @ 2019-07-22 14:09 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> In general, I would argue in favor of fewer "note", "warning", etc.
> Some documentation pages are now just a sequence of "note"s and little
> proper text. If the normal text properly explains a topic and its pros
> and cons, then we don't need all that extra decoration and it makes the
> text easier to read.
+1. With the way these things are rendered in the current HTML output,
they are so visually distracting that they ought to be reserved for
absolutely critical info. I almost feel that we should ban <note>
entirely, because the rendering is completely disproportional to the
meaning.
(Or, maybe, somebody could tinker with the stylesheets?)
regards, tom lane
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Formatting of warning about using ident
@ 2019-07-22 15:30 Jonathan S. Katz <jkatz@postgresql.org>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 7+ messages in thread
From: Jonathan S. Katz @ 2019-07-22 15:30 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org
On 7/22/19 10:09 AM, Tom Lane wrote:
> Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
>> In general, I would argue in favor of fewer "note", "warning", etc.
>> Some documentation pages are now just a sequence of "note"s and little
>> proper text. If the normal text properly explains a topic and its pros
>> and cons, then we don't need all that extra decoration and it makes the
>> text easier to read.
>
> +1. With the way these things are rendered in the current HTML output,
> they are so visually distracting that they ought to be reserved for
> absolutely critical info. I almost feel that we should ban <note>
> entirely, because the rendering is completely disproportional to the
> meaning.
Based on the example of auth-ident.html, removing "note" seems to make
sense. It just seems like it's a part of the regular documentation.
However, perhaps the reason people feel the need to highlight such
things is that they want to ensure the reader catches an important
point, particularly as one is often reading the documentation quickly to
find the piece of info they're looking for (speaking from personal
experience).
That said, looking through some other pages, the "notes" feel like
they're other "asides" to add more detail around a particular point, or
calling out a specific fact. It seems like they could be inlined as part
of the regular documentation.
Something like a "warning" should be visually distracting...it's a
warning that the user could end up in a dangerous situation with their
data, so they should heed it.
> (Or, maybe, somebody could tinker with the stylesheets?)
I think lessening the use of "note" would help. It would require some
rewriting in places it's being used. That way, if we need something
that's truly a "warning" we won't feel as hesitant to add it to the docs.
Thanks,
Jonathan
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Formatting of warning about using ident
@ 2019-07-24 08:28 Daniel Gustafsson <daniel@yesql.se>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
1 sibling, 0 replies; 7+ messages in thread
From: Daniel Gustafsson @ 2019-07-24 08:28 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: pgsql-docs@lists.postgresql.org
> On 22 Jul 2019, at 14:23, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
> Being a quote and being a warning are two orthogonal properties. So in
> that sense, wrapping the quote in a warning element is more correct.
> But the problem is now that a warning box is meant to be formatted out
> of line, so writing something like
>
> <para>This feature does this and that and the other, but
> <warning>
> You can really make a mess with this.
> </warning>
> </para>
>
> is not correct. (I'm surprised the schema even allows this.)
According to the schema it’s legal, warning can be in a para and can itself
contain a para.
> I don't think that would be an improvement though.
I’m not a fan of the status quo, but I don’t feel it’s worth pursuing much
further so I’m withdrawing for now. Thanks for reviewing!
cheers ./daniel
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2019-07-24 08:28 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-06-14 08:47 Formatting of warning about using ident Daniel Gustafsson <daniel@yesql.se>
2019-06-26 13:09 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2019-07-01 11:48 ` Daniel Gustafsson <daniel@yesql.se>
2019-07-22 12:23 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2019-07-22 14:09 ` Tom Lane <tgl@sss.pgh.pa.us>
2019-07-22 15:30 ` Jonathan S. Katz <jkatz@postgresql.org>
2019-07-24 08:28 ` Daniel Gustafsson <daniel@yesql.se>
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