**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: - overstriking or underlining - "filling" RFCs are formatted "ragged right", i.e., left-justified without padding to a straight right margin. - (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. - 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: FF ... When transmitted across the Internet as ASCII text, the character sequence is: CR LF FF CR LF 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.