User Tools

Site Tools


styleweb

This is a DRAFT of the content for the RFC Style Guide dynamic web page

Introduction

The RFC Series is continually evolving to meet the needs of the Internet community. While there are specific and commonly understood recommendations and requirements for RFC, some points are either experimental or transitory in some manner. This website covers those experimental or transitory recommendations from the RFC Editor and makes up the second half of the RFC Style Guide.

As new recommendations are being tested or updated to reflect current usage, this site will change.

Citing other Standard Development Organizations (SDO)

Indicate preference for xml2rfc citation library format

Someone will need to take proper ownership for this citation library

Referencing BCP, STD and associated individual RFC

Standards (STD) and Best Common Practices (BCP) may consist of a single document or as a subseries of documents. When a STD or BCP that contain multiple RFCs is referenced, the reference entry should include ALL of the RFCs comprising that subseries. The authors should refer to specific RFC numbers as part of the text (not as citations) and cite the subseries number.

Should include sample text

[STD62] Harrington, D., Presuhn, R., and B. Wijnen, “An

       Architecture for Describing Simple Network Management
       Protocol (SNMP) Management Frameworks", STD 62,
       RFC 3411, December 2002.
 Case, J., Harrington, D., Presuhn, R., and B. Wijnen, 
       "Message Processing and Dispatching for the Simple 
       Network Management Protocol (SNMP)", STD 62, RFC 3412, 
       December 2002.
 Levi, D., Meyer, P., and B. Stewart, "Simple Network
       Management Protocol (SNMP) Applications", STD 62,
       RFC 3413, December 2002.

...

With this convention, the documents that comprise the STD number at that time of pub are documented and the text is clear where it is referring to a specific document vs the suite of protocols (e.g., “RFC 3412 [STD62] discusses Message Processing Dispatching…” or “The SNMP Standard [STD62] …”).

Referencing I-D in an RFC

This advice is itself a Work in Progress (From the Citation Committee - http://tools.ietf.org/id/draft-carpenter-rfc-citation-recs-01.txt)

 We RECOMMEND that "Working Draft" be used for IETF stream Internet-
 Drafts that have expired and are no longer part of an active IETF
 initiative.  A good sign of such cases is when a newer draft has been
 released or a draft has been expired for over a year.  For all other
 publishing streams, we RECOMMEND that "Working Draft" be used to
 characterize all Internet-Drafts.
 

If a specific version of the I-D is being referenced, reference should also include the full file name in order to capture the revision number.

Judging the stability of a website reference

As more information moves to purely digital form, there is an increased need to be able to reference online, digital documents. One of the requirements of the RFC Editor is that all references, both normative and informative, must be persistent and stable. While this can be difficult to determine, the basic criteria are:

  • the URL provided by the author in the references must be active when checked during the editorial process
  • the URL provided should point to the original document or site when possible for both stability and potential copyright issues
  • the URL provided should point to a reliable and credible source (note that sites like Wikipedia do not consider their content consistently reliable or credible)

Capitalization of author names

Currently, capitalization of author names is at the discretion of the author. Some authors find that capitalizing their surname provides clarity for their preferred name structure. Other authors find this unnecessary. The RFC Editor suggests the following going forward:

  • capitalization may remain at the author's discretion, with the following caveats:
    • use of capitalization must be consistent for an author across all RFCs

Capitalization of file types and compression formats

How to refer to specific sections of reference materials

A question for the citation committee - How to refer to specific sections of referenced materials; e.g., one

author used the following recently:

Device Under Test (DUT) [RFC2285, Section 3.1.1]

Flow [RFC5101, Section 2]

Flow Key [RFC5101, Section 2]

Flow Record [RFC5101, Section 2]

Template Record [RFC5101, Section 2]

Observation Point [RFC5470, Section 2]

Metering Process [RFC5470, Section 2]

Exporting Process [RFC5470, Section 2]

Exporter [RFC5470, Section 2]

Collector [RFC5470, Section 2]

References

Consider allowing for “Additional Reading” - links to materials not directly cited

RFC physical format

Was Appendix B of the RFC Style Guide Draft. Will very likely change significantly with new Format decisions.

  • RFCs are normally published as plain text files in the [US-]ASCII

[RFC20] character set (also known as ISO 646.IRV).

       Only the printable ASCII characters and the three control
       characters CR, LF, and FF are allowed.  They must be used only
       for end-of-line and end-of-page, as described in Appendix B. 
       Tab (HT) characters and Backspace (BS) characters are never
       allowed (hence, there can be no underlining). 
       In certain cases, a supplementary or equivalent Postscript or
       PDF file may be published.  Formatting rules for such a
       Postscript file are given in B.1. 
  • Each line of text is limited to 72 characters, followed by the

character sequence that denotes an end-of-line (EOL).

       The RFC Editor will adjust running text when necessary to fit
       within the 72 character limit.  However, pay particular
       attention to this limit when creating tables, figures, and
       diagrams, as these may not be easily truncated. 
  • Each page is limited to 58 lines followed by a Form Feed (FF)

character, followed by an EOL sequence. This 58 line limit

    includes the headers and footers.   
  • All pages, except perhaps the first and last, must have the same

number of lines when headers and footers are included. That is,

    footers should not "bounce" from page to page. 
  • Text should be single-spaced. There must be one blank line between

paragraphs.

  • In general, readability will be much enhanced by treating each

bulleted item as a paragraph. That is, one blank line should be

    placed between bulleted items. 
  • Pages must be numbered consecutively, starting from 1 on the first

page.

  • An RFC must not contain:
  1. overstriking or underlining
  1. “filling”
          RFCs are formatted "ragged right", i.e., left-justified
          without padding to a straight right margin. 
  1. (added) hyphenation at right margin.
          Do not use hyphenation at the right margin to split existing
          words that do not "naturally" contain hyphens (e.g., "Inter-
          net").  However, hyphenated words (e.g., "Internet-Draft")
          may be split at the hyphen across successive lines. 
          
          NOTE: There are good reasons for the use of "ragged right"
          without hyphenation.  Studies have shown that text is harder
          to read when fixed-size spaces are inserted to adjust the
          right margins, regardless of which font is used or how
          smoothly the blank filler is inserted.  In addition, when
          technical text in a fixed-width font is hyphenated at the
          right margin, the printed result is not only less readable
          but also ugly. 
  1. Footnotes
          Parenthetical notes may be placed at the end of a section or
          at the end of the document, or inserted inline and indented.
           These types of notes are often indented and marked as
          follows:
             NOTE: Insert note here.
  • When a sentence ended by a period is immediately followed by

another sentence, there should be two blank spaces after the

    period.  This rule provides readability when an RFC is displayed
    or printed with a fixed-width font. 

B.1. PostScript Format Rules

 A PostScript file may be submitted for posting in addition to the
 canonical text file.
 (1p) Document should match .txt file as closely as possible in
      structure, format, and content.
 (2p) Standard page size is 8 1/2 by 11 inches (216 by 279 mm).
 (3p) Leave a margin of 1 inch (25 mm) on all sides (top, bottom,
      left, and right).
 (4p) Main text should have a point size of no less than 10 points
      with a line spacing of 12 points.
 (5p) Notes and graph notations no smaller than 8 points with a line
      spacing of 9.6 points.
 (6p) Three fonts are acceptable: Helvetica, Times Roman, and Courier,
      plus their bold-face and italic versions.  These are the three
      standard fonts on most PostScript printers.
 (7p) Prepare diagrams and images based on lowest common denominator
      PostScript.  Consider common PostScript printer functionality
      and memory requirements.
 (8p) The following PostScript commands should not be used:
      initgraphics, erasepage, copypage, grestoreall, initmatrix,
      initclip, banddevice, framedevice, nulldevice or renderbands.

B.2. End-of-Line and End-of-Page

 A plain-text RFC is expected to be stored on a disk file using the
 EOL sequence of that system.  For example, MS DOS-based systems use
 the two-character sequence: CR LF (Carriage Return followed by Line
 Feed), Unix systems use the single character LF for EOL, and EBCDIC
 systems use the single character NL (New Line).  Whenever an RFC is
 transmitted across the Internet, Internet protocol convention
 requires that each line of text be followed by the two-character EOL
 sequence CR LF (Carriage Return followed by Line Feed). A user level
 protocol (e.g., FTP, Telnet, HTTP, SMTP, ...) must make the
 appropriate EOL transformation at each line end.  Note that binary
 transmission of plain-text RFC files can cause the sender's EOL
 convention to "leak" into the receiver, causing confusion. 
 The maximum line count of 58 lines includes blank lines.  However,
 the first line will normally be the first header line and the last
 line will be the final footer line; that is, it will not begin or end
 with a blank line. 
 Note that 58 lines is the maximum; 55 is more commonly used and may
 actually produce more readable formatting.  The recommended page
 formatting parameters produce 55 line pages on many printers, for
 example.
 The effect of the Height rule is that the following ASCII character
 sequence will be used: 
          <Last non-blank line of page p> <EOL> FF <EOL>
                          <First line of page p+1> <EOL> ...
 When transmitted across the Internet as ASCII text, the character
 sequence is: 
          <Last non-blank line of page p> CR LF FF CR LF
                          <First line of page p+1> CR LF ...
 Finally, note that the sequence FF CR LF has an ambiguous effect: on
 some printers, the FF implies an EOL, so this may produce a blank
 line; on other printers it will produce no blank line.  The number 58
 and this sequence were designed to render this ambiguity unimportant,
 assuming the (once predominant) printer standard of 60 lines per
 page.
styleweb.txt · Last modified: 2012/10/12 20:45 by rsewikiadmin