RFC Reader Script

It is often useful to read RFCs of the Internet Engineering Task Force (IETF) when trying to understand some networking issue or differences in vendor implementations. RFCs can be read using a web browser, e.g. via the IETF provided IETF Documents (preferred web site, the URLs look like https://tools.ietf.org/html/rfc<NUMBER>) or rfcmarkup.cgi pages, or using my Show RFC OpenSearch plugin. The problem with this approach is RFC pagination, which is not used in the web pages. Thus the header and footer line included as normal text in an RFC disturb the reading flow in a web browser.

If only a web browser is available, the PDF rendering of an RFC is often the better choice than the HTML version.

When using a GNU/Linux system I prefer to retrieve the RFC text version with GNU wget, (slightly) reformat the text using a small AWK script, and displaying it inside an appropriately sized XTerm (or other terminal emulator window) using the less pager. This allows flipping through the pages similar to a printed RFC. If the system supports UTF-8, e.g. using a relatively recent GNU/Linux distribution with default configuration, this supports use of UTF-8 as found in RFC 8187.

I have written a small shell script called rfc-reader to do just this.

Besides the download link on this page, it is part of my collection of single file tools in a git repository on GitHub. A change log for rfc-reader can be found in form of the git commit log.

Usage

rfc-reader [{rfc[-]|bcp|fyi|ien|std}][ ]NUMBER[.txt]

Examples

rfc-reader 1        # downloads and displays RFC 1
rfc-reader rfc1     # downloads and displays RFC 1
rfc-reader rfc 1    # downloads and displays RFC 1
rfc-reader rfc1.txt # downloads and displays RFC 1
rfc-reader bcp78    # downloads and displays BCP 78
rfc-reader fyi3     # downloads and displays FYI 3
rfc-reader ien137   # downloads and displays IEN 137
rfc-reader std1     # downloads and displays STD 1

Local RFC Storage

Some GNU/Linux Distributions include packages containing RFCs. rfc-reader looks for RFC files in the following directories, used by OpenSUSE and Debian/Ubuntu respectively:

/usr/share/doc/rfc
/usr/share/doc/RFC/links

If you know of additional locations used by GNU/Linux distributions or other operating systems to provide local RFC copies, please let me know.

Cache for Downloaded RFC Files

If the directory $HOME/.rfc-reader/cache exists and is readable, rfc-reader will look for RFC files there. If the directory is writable, rfc-reader will use it to save downloaded RFC files.

Screenshots

Using XTerm and less

[image of rfc-reader using XTerm and less]

Significant Options

XTerm:
-fn c-9x18 -fg green -bg black -bd green -g 72x59
less:
-M -S
(For full options see the actual script.)

Using GNOME Terminal and less

[image of rfc-reader using GNOME Terminal and less]

Significant Options

GNOME Terminal:
--hide-menubar --disable-factory --geometry 72x59
less:
-M -S
(For full options see the actual script.)

Note on GNOME Terminal Use

Starting rfc-reader as a background job does not work well with GNOME Terminal. There seems to be a race regarding setting the terminal dimensions and starting the pager inside the terminal. The result is a wrong output size inside the pager. As a workaround you can start rfc-reader in the foreground, suspend it (usually CTRL+Z in the terminal it was started from), and then make it a background process with bg.

The problem mentioned above does not occur with XTerm.

On Re-Formatting the RFC

The RFCs use a format that works well when printed on paper. Thus it uses pages with headers and footers. All pages are roughly the same size, one which fits the paper size of most text printers (but actual RFC page size varies slightly). This does not work well with the variable size of screens, terminal windows, and fonts. So called pagers (like less) usually adapt to the current screen resp. window size and allow continuous scolling through the text, losing the benefits of pagination. Worse, headers and footers interrupt reading instead of unobtrusively providing reference information.

A text document comprised of pages with a fixed number of lines, the first and last used as header and footer, looks good in a pager providing exactly the same number of lines. Since RFCs have a defined maximum number of lines (58) and maximum number of characters per line (72) [see RFC 2223], using a text display area of this size should work fine, but not all pages in an RFC have the same length. For printing, use of the form feed character (FF, ASCII code 12) ends a page. Pagers usually do not use this convention. Therefore my rfc-reader script fills all pages to be of equal length (58 lines), allowing paginated reading on screen in an appropriatly sized text window showing the pager output.

To display an RFC in text format with a pager inside a sufficiently large terminal, the form feed character should be expanded to fill the terminal (excluding the status line of the pager). When using a shell that sets the LINES envirtonment variable, e.g. GNU Bash, this can be done as follows (using less as pager):

awk -vn_lines="${LINES}" '!/\f/ {line++; print}; /\f/ {for (i=line; i+1<n_lines; i++) print ""; line=0}; END {for (i=line; i+1<n_lines; i++) print ""}' RFC.txt | less -S

(RFC 6949 drops the pagination requirements (section 3.3), thus the rfc-reader script will lose its usefulness for new RFCs some time in the future, but will remain very helpful for RFCs published according to RFC 2223. This includes the published well-paginated RFCs since there is no plan to re-publish them in the new format.)


back to my homepage.