pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedConsistent reference to RFCs in the documentation
4+ messages / 3 participants
[nested] [flat]
Commits from this thread:
2020-12-01 415dc20096 docs: ulink all references to RFC's
* Consistent reference to RFCs in the documentation
@ 2020-11-05 15:09 Daniel Gustafsson <daniel@yesql.se>
2020-12-01 12:39 ` Re: Consistent reference to RFCs in the documentation Heikki Linnakangas <hlinnaka@iki.fi>
0 siblings, 1 reply; 4+ messages in thread
From: Daniel Gustafsson @ 2020-11-05 15:09 UTC (permalink / raw)
To: Pg Docs <pgsql-docs@lists.postgresql.org>
When referencing RFC's, we have a mix of ulinking to the ietf.org entry and
not. Also, for subsequent mentions of the same RFC on the same page we have
some as <acronym> while others are not. The attached patch adds ulinks for all
RFC's and marks subsequent mentions as acronym to make the docs consistent. It
also spells all as "RFC <number>" with a whitespace as that was the most
commonly used spelling (there is no RFC for how to reference to an RFC so we're
free to choose).
In order to make review easier I haven't fixed linelengths/wrapping, but am
happy to do that in case this is deemed something we want.
cheers ./daniel
Attachments:
0001-docs-ulink-all-references-to-RFC-s.patch (application/octet-stream, 14.2K) download
From 77b02fee33ff4d582097f0ab449bfb939c455f22 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Thu, 5 Nov 2020 16:00:27 +0100
Subject: [PATCH] docs: ulink all references to RFC's
Make sure that the first mentions of RFC's are ulinked to their ietf.org
entry, and subsequent ones are marked as acronyms. This makes references
to RFC's consistent across the documentation.
---
doc/src/sgml/catalogs.sgml | 2 +-
doc/src/sgml/charset.sgml | 2 +-
doc/src/sgml/client-auth.sgml | 12 ++++++------
doc/src/sgml/datatype.sgml | 4 ++--
doc/src/sgml/ecpg.sgml | 2 +-
doc/src/sgml/func.sgml | 2 +-
doc/src/sgml/json.sgml | 4 ++--
doc/src/sgml/libpq.sgml | 2 +-
doc/src/sgml/pgcrypto.sgml | 6 +++---
doc/src/sgml/protocol.sgml | 4 ++--
doc/src/sgml/textsearch.sgml | 2 +-
doc/src/sgml/uuid-ossp.sgml | 4 ++--
12 files changed, 23 insertions(+), 23 deletions(-)
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 5fb9dca425..15b8374822 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1598,7 +1598,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
</synopsis>
where <replaceable>salt</replaceable>, <replaceable>StoredKey</replaceable> and
<replaceable>ServerKey</replaceable> are in Base64 encoded format. This format is
- the same as that specified by RFC 5803.
+ the same as that specified by <ulink url="https://tools.ietf.org/html/rfc5803">RFC 5803</ulink>.
</para>
<para>
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 832a701523..d744267785 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -2662,7 +2662,7 @@ RESET client_encoding;
</varlistentry>
<varlistentry>
- <term>RFC 3629</term>
+ <term><ulink url="https://tools.ietf.org/html/rfc3629">RFC 3629</ulink></term>
<listitem>
<para>
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index bad3c3469c..502b76815f 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -948,7 +948,7 @@ omicron bryanh guest1
<listitem>
<para>
<link linkend="auth-ident">Ident authentication</link>, which
- relies on an <quote>Identification Protocol</quote> (RFC 1413)
+ relies on an <quote>Identification Protocol</quote> (<ulink url="https://tools.ietf.org/html/rfc1413">RFC 1413</ulink>)
service on the client's machine. (On local Unix-socket connections,
this is treated as peer authentication.)
</para>
@@ -1198,7 +1198,7 @@ omicron bryanh guest1
<para>
<productname>GSSAPI</productname> is an industry-standard protocol
- for secure authentication defined in RFC 2743.
+ for secure authentication defined in <ulink url="https://tools.ietf.org/html/rfc2743">RFC 2743</ulink>.
<productname>PostgreSQL</productname>
supports <productname>GSSAPI</productname> for use as either an encrypted,
@@ -1503,7 +1503,7 @@ omicron bryanh guest1
<para>
The <quote>Identification Protocol</quote> is described in
- RFC 1413. Virtually every Unix-like
+ <ulink url="https://tools.ietf.org/html/rfc1413">RFC 1413</ulink>. Virtually every Unix-like
operating system ships with an ident server that listens on TCP
port 113 by default. The basic functionality of an ident server
is to answer questions like <quote>What user initiated the
@@ -1671,7 +1671,7 @@ omicron bryanh guest1
<para>
Set to 1 to make the connection between PostgreSQL and the LDAP server
use TLS encryption. This uses the <literal>StartTLS</literal>
- operation per RFC 4513. See also the <literal>ldapscheme</literal>
+ operation per <ulink url="https://tools.ietf.org/html/rfc4513">RFC 4513</ulink>. See also the <literal>ldapscheme</literal>
option for an alternative.
</para>
</listitem>
@@ -1766,7 +1766,7 @@ omicron bryanh guest1
<term><literal>ldapurl</literal></term>
<listitem>
<para>
- An RFC 4516 LDAP URL. This is an alternative way to write some of the
+ An <ulink url="https://tools.ietf.org/html/rfc4516">RFC 4516</ulink> LDAP URL. This is an alternative way to write some of the
other LDAP options in a more compact and standard form. The format is
<synopsis>
ldap[s]://<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/<replaceable>basedn</replaceable>[?[<replaceable>attribute</replaceable>][?[<replaceable>scope</replaceable>][?[<replaceable>filter</replaceable>]]]]
@@ -1827,7 +1827,7 @@ ldap[s]://<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/<rep
If <productname>PostgreSQL</productname> was compiled with
<productname>OpenLDAP</productname> as the LDAP client library, the
<literal>ldapserver</literal> setting may be omitted. In that case, a
- list of host names and ports is looked up via RFC 2782 DNS SRV records.
+ list of host names and ports is looked up via <ulink url="https://tools.ietf.org/html/rfc2782">RFC 2782</ulink> DNS SRV records.
The name <literal>_ldap._tcp.DOMAIN</literal> is looked up, where
<literal>DOMAIN</literal> is extracted from <literal>ldapbasedn</literal>.
</para>
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index c2951854b5..6667b69189 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2384,7 +2384,7 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
ISO 8601 specifies the use of uppercase letter <literal>T</literal> to separate
the date and time. <productname>PostgreSQL</productname> accepts that format on
input, but on output it uses a space rather than <literal>T</literal>, as shown
- above. This is for readability and for consistency with RFC 3339 as
+ above. This is for readability and for consistency with <ulink url="https://tools.ietf.org/html/rfc3339">RFC 3339</ulink> as
well as some other database systems.
</para>
</note>
@@ -4247,7 +4247,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' );
<para>
The data type <type>uuid</type> stores Universally Unique Identifiers
- (UUID) as defined by RFC 4122, ISO/IEC 9834-8:2005, and related standards.
+ (UUID) as defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink>, ISO/IEC 9834-8:2005, and related standards.
(Some systems refer to this data type as a globally unique identifier, or
GUID,<indexterm><primary>GUID</primary></indexterm> instead.) This
identifier is a 128-bit quantity that is generated by an algorithm chosen
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index 14dcbdb4e3..0fef9bfcbe 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -3226,7 +3226,7 @@ int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmt
<literal>%z</literal> - is replaced by the time zone offset from
UTC; a leading plus sign stands for east of UTC, a minus sign for
west of UTC, hours and minutes follow with two digits each and no
- delimiter between them (common form for RFC 822 date headers).
+ delimiter between them (common form for <ulink url="https://tools.ietf.org/html/rfc822">RFC 822</ulink> date headers).
</para>
</listitem>
<listitem>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 87a6ba8d10..659d708ea1 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -4466,7 +4466,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
<para>
The <literal>base64</literal> format is that
of <ulink url="https://tools.ietf.org/html/rfc2045#section-6.8">RFC
- 2045 Section 6.8</ulink>. As per the RFC, encoded lines are
+ 2045 Section 6.8</ulink>. As per the <acronym>RFC</acronym>, encoded lines are
broken at 76 characters. However instead of the MIME CRLF
end-of-line marker, only a newline is used for end-of-line.
The <function>decode</function> function ignores carriage-return,
diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml
index c0a6554d4d..5b9a5557a4 100644
--- a/doc/src/sgml/json.sgml
+++ b/doc/src/sgml/json.sgml
@@ -61,7 +61,7 @@
</para>
<para>
- RFC 7159 specifies that JSON strings should be encoded in UTF8.
+ <acronym>RFC</acronym> 7159 specifies that JSON strings should be encoded in UTF8.
It is therefore not possible for the JSON
types to conform rigidly to the JSON specification unless the database
encoding is UTF8. Attempts to directly include characters that
@@ -71,7 +71,7 @@
</para>
<para>
- RFC 7159 permits JSON strings to contain Unicode escape sequences
+ <acronym>RFC</acronym> 7159 permits JSON strings to contain Unicode escape sequences
denoted by <literal>\u<replaceable>XXXX</replaceable></literal>. In the input
function for the <type>json</type> type, Unicode escapes are allowed
regardless of the database encoding, and are checked only for syntactic
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 9ce32fb39b..4e1d052502 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -7447,7 +7447,7 @@ user=admin
<literal>ldap://</literal> will be recognized as an LDAP URL and an
LDAP query will be performed. The result must be a list of
<literal>keyword = value</literal> pairs which will be used to set
- connection options. The URL must conform to RFC 1959 and be of the
+ connection options. The URL must conform to <ulink url="https://tools.ietf.org/html/rfc1959">RFC 1959</ulink> and be of the
form
<synopsis>
ldap://[<replaceable>hostname</replaceable>[:<replaceable>port</replaceable>]]/<replaceable>search_base</replaceable>?<replaceable>attribute</replaceable>?<replaceable>search_scope</replaceable>?<replaceable>filter</replaceable>
diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index 8748c64e2d..f5ca0c820b 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -437,7 +437,7 @@ gen_salt(type text [, iter_count integer ]) returns text
<title>PGP Encryption Functions</title>
<para>
- The functions here implement the encryption part of the OpenPGP (RFC 4880)
+ The functions here implement the encryption part of the OpenPGP (<ulink url="https://tools.ietf.org/html/rfc4880">RFC 4880</ulink>)
standard. Supported are both symmetric-key and public-key encryption.
</para>
@@ -806,7 +806,7 @@ Applies to: pgp_sym_encrypt, pgp_pub_encrypt
<para>
Whether to convert <literal>\n</literal> into <literal>\r\n</literal> when
encrypting and <literal>\r\n</literal> to <literal>\n</literal> when
- decrypting. RFC 4880 specifies that text data should be stored using
+ decrypting. <acronym>RFC</acronym> 4880 specifies that text data should be stored using
<literal>\r\n</literal> line-feeds. Use this to get fully RFC-compliant
behavior.
</para>
@@ -823,7 +823,7 @@ Applies to: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt
<para>
Do not protect data with SHA-1. The only good reason to use this
option is to achieve compatibility with ancient PGP products, predating
- the addition of SHA-1 protected packets to RFC 4880.
+ the addition of SHA-1 protected packets to <acronym>RFC</acronym> 4880.
Recent gnupg.org and pgp.com software supports it fine.
</para>
<literallayout>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9a95d7b734..eca1299cbd 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1501,7 +1501,7 @@ SELCT 1/0;<!-- this typo is intentional -->
is willing or unwilling to perform <acronym>GSSAPI</acronym> encryption,
respectively. The frontend might close the connection at this point
if it is dissatisfied with the response. To continue after
- <literal>G</literal>, using the GSSAPI C bindings as discussed in RFC2744
+ <literal>G</literal>, using the GSSAPI C bindings as discussed in <ulink url="https://tools.ietf.org/html/rfc2744">RFC 2744</ulink>
or equivalent, perform a <acronym>GSSAPI</acronym> initialization by
calling <function>gss_init_sec_context()</function> in a loop and sending
the result to the server, starting with an empty input and then with each
@@ -1616,7 +1616,7 @@ ErrorMessage.
The implemented SASL mechanisms at the moment
are <literal>SCRAM-SHA-256</literal> and its variant with channel
binding <literal>SCRAM-SHA-256-PLUS</literal>. They are described in
- detail in RFC 7677 and RFC 5802.
+ detail in <ulink url="https://tools.ietf.org/html/rfc7677">RFC 7677</ulink> and <ulink url="https://tools.ietf.org/html/rfc5802">RFC 5802</ulink>.
</para>
<para>
diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index 7bd8d53dc4..aa00a2139a 100644
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -2218,7 +2218,7 @@ LIMIT 10;
<para>
<literal>email</literal> does not support all valid email characters as
- defined by RFC 5322. Specifically, the only non-alphanumeric
+ defined by <ulink url="https://tools.ietf.org/html/rfc5322">RFC 5322</ulink>. Specifically, the only non-alphanumeric
characters supported for email user names are period, dash, and
underscore.
</para>
diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml
index 460be97fdd..d4dd678f67 100644
--- a/doc/src/sgml/uuid-ossp.sgml
+++ b/doc/src/sgml/uuid-ossp.sgml
@@ -28,8 +28,8 @@
<para>
<xref linkend="uuid-ossp-functions"/> shows the functions available to
generate UUIDs.
- The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and RFC
- 4122 specify four algorithms for generating UUIDs, identified by the
+ The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and <ulink url="https://tools.ietf.org/html/rfc4122">RFC
+ 4122</ulink> specify four algorithms for generating UUIDs, identified by the
version numbers 1, 3, 4, and 5. (There is no version 2 algorithm.)
Each of these algorithms could be suitable for a different set of
applications.
--
2.21.1 (Apple Git-122.3)
=
* Re: Consistent reference to RFCs in the documentation
2020-11-05 15:09 Consistent reference to RFCs in the documentation Daniel Gustafsson <daniel@yesql.se>
@ 2020-12-01 12:39 ` Heikki Linnakangas <hlinnaka@iki.fi>
2020-12-01 12:55 ` Re: Consistent reference to RFCs in the documentation Daniel Gustafsson <daniel@yesql.se>
2020-12-02 19:21 ` Re: Consistent reference to RFCs in the documentation Bruce Momjian <bruce@momjian.us>
0 siblings, 2 replies; 4+ messages in thread
From: Heikki Linnakangas @ 2020-12-01 12:39 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; Pg Docs <pgsql-docs@lists.postgresql.org>
On 05/11/2020 17:09, Daniel Gustafsson wrote:
> When referencing RFC's, we have a mix of ulinking to the ietf.org entry and
> not. Also, for subsequent mentions of the same RFC on the same page we have
> some as <acronym> while others are not.
I'm not sure how sensible the <acronym> tag is for these. I mean, yeah,
it's an acronym, but it wouldn't make sense to write it open. It doesn't
seem to affect the formatting in the HTML docs, at least I don't see any
difference in my browser. But let's be consistent.
> The attached patch adds ulinks for all
> RFC's and marks subsequent mentions as acronym to make the docs consistent. It
> also spells all as "RFC <number>" with a whitespace as that was the most
> commonly used spelling (there is no RFC for how to reference to an RFC so we're
> free to choose).
There is RFC 7322, "RFC Style Guide", Section 3.5 Citations
(https://tools.ietf.org/html/rfc7322#section-3.5). That's for the style
used in RFCs themselves. It recommends "RFC <number>" as well.
> In order to make review easier I haven't fixed linelengths/wrapping, but am
> happy to do that in case this is deemed something we want.
I line-wrapped some of them manually. We're not terribly consistent with
the wrapping in the docs.
Pushed, thanks!
- Heikki
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Consistent reference to RFCs in the documentation
2020-11-05 15:09 Consistent reference to RFCs in the documentation Daniel Gustafsson <daniel@yesql.se>
2020-12-01 12:39 ` Re: Consistent reference to RFCs in the documentation Heikki Linnakangas <hlinnaka@iki.fi>
@ 2020-12-01 12:55 ` Daniel Gustafsson <daniel@yesql.se>
1 sibling, 0 replies; 4+ messages in thread
From: Daniel Gustafsson @ 2020-12-01 12:55 UTC (permalink / raw)
To: Heikki Linnakangas <hlinnaka@iki.fi>; +Cc: Pg Docs <pgsql-docs@lists.postgresql.org>
> On 1 Dec 2020, at 13:39, Heikki Linnakangas <hlinnaka@iki.fi> wrote:
> On 05/11/2020 17:09, Daniel Gustafsson wrote:
>> The attached patch adds ulinks for all
>> RFC's and marks subsequent mentions as acronym to make the docs consistent. It
>> also spells all as "RFC <number>" with a whitespace as that was the most
>> commonly used spelling (there is no RFC for how to reference to an RFC so we're
>> free to choose).
>
> There is RFC 7322, "RFC Style Guide", Section 3.5 Citations (https://tools.ietf.org/html/rfc7322#section-3.5). That's for the style used in RFCs themselves. It recommends "RFC <number>" as well.
Interesting, I've looked for that more than once but failed to find that
section. Thanks for pointing it out.
> Pushed, thanks!
Thanks!
cheers ./daenil
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Consistent reference to RFCs in the documentation
2020-11-05 15:09 Consistent reference to RFCs in the documentation Daniel Gustafsson <daniel@yesql.se>
2020-12-01 12:39 ` Re: Consistent reference to RFCs in the documentation Heikki Linnakangas <hlinnaka@iki.fi>
@ 2020-12-02 19:21 ` Bruce Momjian <bruce@momjian.us>
1 sibling, 0 replies; 4+ messages in thread
From: Bruce Momjian @ 2020-12-02 19:21 UTC (permalink / raw)
To: Heikki Linnakangas <hlinnaka@iki.fi>; +Cc: Daniel Gustafsson <daniel@yesql.se>; Pg Docs <pgsql-docs@lists.postgresql.org>
On Tue, Dec 1, 2020 at 02:39:04PM +0200, Heikki Linnakangas wrote:
> On 05/11/2020 17:09, Daniel Gustafsson wrote:
> > When referencing RFC's, we have a mix of ulinking to the ietf.org entry and
> > not. Also, for subsequent mentions of the same RFC on the same page we have
> > some as <acronym> while others are not.
>
> I'm not sure how sensible the <acronym> tag is for these. I mean, yeah, it's
> an acronym, but it wouldn't make sense to write it open. It doesn't seem to
> affect the formatting in the HTML docs, at least I don't see any difference
> in my browser. But let's be consistent.
Ideally acronyms would use smallcaps, but I don't think we have that
configured in our style sheets.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2020-12-02 19:21 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-11-05 15:09 Consistent reference to RFCs in the documentation Daniel Gustafsson <daniel@yesql.se>
2020-12-01 12:39 ` Heikki Linnakangas <hlinnaka@iki.fi>
2020-12-01 12:55 ` Daniel Gustafsson <daniel@yesql.se>
2020-12-02 19:21 ` Bruce Momjian <bruce@momjian.us>
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