Subject: Re: Consistent reference to RFCs in the documentation
To: Daniel Gustafsson <daniel@yesql.se>,
 Pg Docs <pgsql-docs@lists.postgresql.org>
References: <2C697878-4D01-4F06-8312-2FEDE931E973@yesql.se>
From: Heikki Linnakangas <hlinnaka@iki.fi>
Message-ID: <a06ea0f1-8aa0-3cee-0587-f895387cda12@iki.fi>
Date: Tue, 1 Dec 2020 14:39:04 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101
 Thunderbird/78.4.0
MIME-Version: 1.0
In-Reply-To: <2C697878-4D01-4F06-8312-2FEDE931E973@yesql.se>
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

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