Re: Consistent reference to RFCs in the documentation

From: Heikki Linnakangas <hlinnaka(at)iki(dot)fi>
To: Daniel Gustafsson <daniel(at)yesql(dot)se>, Pg Docs <pgsql-docs(at)lists(dot)postgresql(dot)org>
Subject: Re: Consistent reference to RFCs in the documentation
Date: 2020-12-01 12:39:04
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-docs

On 05/11/2020 17:09, Daniel Gustafsson wrote:
> When referencing RFC's, we have a mix of ulinking to the 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
( 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

In response to


Browse pgsql-docs by date

  From Date Subject
Next Message Daniel Gustafsson 2020-12-01 12:55:27 Re: Consistent reference to RFCs in the documentation
Previous Message Jürgen Purtz 2020-12-01 08:38:20 Re: Change JOIN tutorial to focus more on explicit joins