Consistent reference to RFCs in the documentation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Consistent reference to RFCs in the documentation

Daniel Gustafsson
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


0001-docs-ulink-all-references-to-RFC-s.patch (20K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Consistent reference to RFCs in the documentation

Heikki Linnakangas
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


Reply | Threaded
Open this post in threaded view
|

Re: Consistent reference to RFCs in the documentation

Daniel Gustafsson
> On 1 Dec 2020, at 13:39, Heikki Linnakangas <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Consistent reference to RFCs in the documentation

Bruce Momjian
In reply to this post by Heikki Linnakangas
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  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee