From 415dc2009683904f337a1837b6b4eb7f31c4dc55 Mon Sep 17 00:00:00 2001 From: Heikki Linnakangas Date: Tue, 1 Dec 2020 14:36:30 +0200 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. Author: Daniel Gustafsson Discussion: https://www.postgresql.org/message-id/2C697878-4D01-4F06-8312-2FEDE931E973%40yesql.se --- doc/src/sgml/catalogs.sgml | 2 +- doc/src/sgml/charset.sgml | 2 +- doc/src/sgml/client-auth.sgml | 19 ++++++++++++------- doc/src/sgml/datatype.sgml | 6 ++++-- doc/src/sgml/ecpg.sgml | 2 +- doc/src/sgml/func.sgml | 2 +- doc/src/sgml/json.sgml | 4 ++-- doc/src/sgml/libpq.sgml | 5 +++-- doc/src/sgml/pgcrypto.sgml | 7 ++++--- doc/src/sgml/protocol.sgml | 6 ++++-- doc/src/sgml/textsearch.sgml | 6 +++--- doc/src/sgml/uuid-ossp.sgml | 5 +++-- 12 files changed, 39 insertions(+), 27 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 569841398b..79069ddfab 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1598,7 +1598,7 @@ SCRAM-SHA-256$<iteration count>:&l where salt, StoredKey and ServerKey are in Base64 encoded format. This format is - the same as that specified by RFC 5803. + the same as that specified by RFC 5803. diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml index e151987eff..cebc09ef91 100644 --- a/doc/src/sgml/charset.sgml +++ b/doc/src/sgml/charset.sgml @@ -2663,7 +2663,7 @@ RESET client_encoding; - RFC 3629 + RFC 3629 diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index bad3c3469c..a0a9ac9eed 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -948,7 +948,8 @@ omicron bryanh guest1 Ident authentication, which - relies on an Identification Protocol (RFC 1413) + relies on an Identification Protocol + (RFC 1413) service on the client's machine. (On local Unix-socket connections, this is treated as peer authentication.) @@ -1198,7 +1199,8 @@ omicron bryanh guest1 GSSAPI is an industry-standard protocol - for secure authentication defined in RFC 2743. + for secure authentication defined in + RFC 2743. PostgreSQL supports GSSAPI for use as either an encrypted, @@ -1503,7 +1505,8 @@ omicron bryanh guest1 The Identification Protocol is described in - RFC 1413. Virtually every Unix-like + RFC 1413. + 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 What user initiated the @@ -1671,8 +1674,8 @@ omicron bryanh guest1 Set to 1 to make the connection between PostgreSQL and the LDAP server use TLS encryption. This uses the StartTLS - operation per RFC 4513. See also the ldapscheme - option for an alternative. + operation per RFC 4513. + See also the ldapscheme option for an alternative. @@ -1766,7 +1769,8 @@ omicron bryanh guest1 ldapurl - An RFC 4516 LDAP URL. This is an alternative way to write some of the + An RFC 4516 + 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 ldap[s]://host[:port]/basedn[?[attribute][?[scope][?[filter]]]] @@ -1827,7 +1831,8 @@ ldap[s]://host[:port]/PostgreSQL was compiled with OpenLDAP as the LDAP client library, the ldapserver 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 + RFC 2782 DNS SRV records. The name _ldap._tcp.DOMAIN is looked up, where DOMAIN is extracted from ldapbasedn. diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index c2951854b5..5c8a92e250 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -2384,7 +2384,8 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' ISO 8601 specifies the use of uppercase letter T to separate the date and time. PostgreSQL accepts that format on input, but on output it uses a space rather than T, as shown - above. This is for readability and for consistency with RFC 3339 as + above. This is for readability and for consistency with + RFC 3339 as well as some other database systems. @@ -4247,7 +4248,8 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); The data type uuid stores Universally Unique Identifiers - (UUID) as defined by RFC 4122, ISO/IEC 9834-8:2005, and related standards. + (UUID) as defined by RFC 4122, + ISO/IEC 9834-8:2005, and related standards. (Some systems refer to this data type as a globally unique identifier, or GUID,GUID 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 %z - 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 RFC 822 date headers). diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 1ea88a8c67..df29af6371 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -4449,7 +4449,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); The base64 format is that of RFC - 2045 Section 6.8. As per the RFC, encoded lines are + 2045 Section 6.8. As per the RFC, 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 decode 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 @@ - RFC 7159 specifies that JSON strings should be encoded in UTF8. + RFC 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 @@ - RFC 7159 permits JSON strings to contain Unicode escape sequences + RFC 7159 permits JSON strings to contain Unicode escape sequences denoted by \uXXXX. In the input function for the json 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 1553f9c89c..67c5d4c36b 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -7462,8 +7462,9 @@ user=admin ldap:// will be recognized as an LDAP URL and an LDAP query will be performed. The result must be a list of keyword = value pairs which will be used to set - connection options. The URL must conform to RFC 1959 and be of the - form + connection options. The URL must conform to + RFC 1959 + and be of the form ldap://[hostname[:port]]/search_base?attribute?search_scope?filter diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml index 8748c64e2d..3d74e15ec9 100644 --- a/doc/src/sgml/pgcrypto.sgml +++ b/doc/src/sgml/pgcrypto.sgml @@ -437,7 +437,8 @@ gen_salt(type text [, iter_count integer ]) returns text PGP Encryption Functions - The functions here implement the encryption part of the OpenPGP (RFC 4880) + The functions here implement the encryption part of the OpenPGP + (RFC 4880) standard. Supported are both symmetric-key and public-key encryption. @@ -806,7 +807,7 @@ Applies to: pgp_sym_encrypt, pgp_pub_encrypt Whether to convert \n into \r\n when encrypting and \r\n to \n when - decrypting. RFC 4880 specifies that text data should be stored using + decrypting. RFC 4880 specifies that text data should be stored using \r\n line-feeds. Use this to get fully RFC-compliant behavior. @@ -823,7 +824,7 @@ Applies to: pgp_sym_encrypt, pgp_pub_encrypt, pgp_sym_decrypt, pgp_pub_decrypt 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 RFC 4880. Recent gnupg.org and pgp.com software supports it fine. diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index cee28889e1..4899bacda7 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1501,7 +1501,8 @@ SELCT 1/0; is willing or unwilling to perform GSSAPI encryption, respectively. The frontend might close the connection at this point if it is dissatisfied with the response. To continue after - G, using the GSSAPI C bindings as discussed in RFC2744 + G, using the GSSAPI C bindings as discussed in + RFC 2744 or equivalent, perform a GSSAPI initialization by calling gss_init_sec_context() in a loop and sending the result to the server, starting with an empty input and then with each @@ -1616,7 +1617,8 @@ ErrorMessage. The implemented SASL mechanisms at the moment are SCRAM-SHA-256 and its variant with channel binding SCRAM-SHA-256-PLUS. They are described in - detail in RFC 7677 and RFC 5802. + detail in RFC 7677 + and RFC 5802. diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml index 7bd8d53dc4..1e52d193b4 100644 --- a/doc/src/sgml/textsearch.sgml +++ b/doc/src/sgml/textsearch.sgml @@ -2218,9 +2218,9 @@ LIMIT 10; email does not support all valid email characters as - defined by RFC 5322. Specifically, the only non-alphanumeric - characters supported for email user names are period, dash, and - underscore. + defined by RFC 5322. + Specifically, the only non-alphanumeric characters supported for + email user names are period, dash, and underscore. diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml index 460be97fdd..359d3c0128 100644 --- a/doc/src/sgml/uuid-ossp.sgml +++ b/doc/src/sgml/uuid-ossp.sgml @@ -28,8 +28,9 @@ 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 + RFC 4122 + 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.