.\" Description: Internet-Draft/RFC source for Writing Internet-Drafts and Requests For Comments using troff and nroff .\" for text version, process as: rfcref | dformat | neqn | grap | pic | tbl | abnff | nroff -Tascii -mrfc | awk -f repaginate,awk .\" for pdf version, generate PostScript for conversion to "letter" size PDF by processing as: rfcref | dformat | eqn | grap | pic | tbl | abnff | troff -Tps -mrfc | awk f psrenumber.awk .\" long version of document title .TL "Writing Internet-Drafts and Requests For Comments using troff and\ \& nroff .\" short version of title for page header .ST "Writing I-Ds and RFCs using troff .\" Date .\" .DT 2005 5 5 .\" author information .AU "B. Lilly" Bruce Lilly m blilly@erols.com "" "" "" "" .\" internet-draft file name (internet drafts only; ignored for RFCs) .FN draft-lilly-using-troff .\" Table of Contents .TC 1 2 .\" Category (RFCs; Intended status for drafts) (one of: Informational, Standards Track, Experimental, Best Current Practice) .CA Informational .\" updates RFCs (if any) .\" .IS .UP 2223 .AB Internet\-Drafts and RFCs have traditionally been produced using a variety of tools, including nroff. This memo describes production of Internet\-Drafts and RFCs using a set of troff/nroff macros suitable for that purpose. Public comments regarding this memo may be sent to the rfc\-interest mailing list. .\" Introduction (first numbered section, in TOC) .NH 1 Introduction .IP The Instructions to RFC Authors RFC .RR N 2223 r1 \& describes the editorial format of RFCs and outlines editorial production of Internet\-Drafts and RFCs using basic troff directives .IR CSTR54 r2 Ossanna, Joseph F., "NROFF/TROFF User's Manual", Computing Science Technical Report No.54, Bell Laboratories, Murray Hill, New Jersey, 1976. .IE \& with the ms macro package .IR ms Lesk, M. E., "Typing Documents on the UNIX System: Using the \-ms Macros with Troff and Nroff", 1978, in "UNIX TIME\-SHARING SYSTEM (VOLUME\ 2): UNIX Programmer's Manual", Holt, Rinehart, & Winston, 1979 .IE \& and a postprocessor which is necessitated by use of the ms macro package. However, use of basic directives and the ms macro package is not ideal. .NH 2 "Basic Directives Are at Too Low a Level .IP Use of basic troff directives is not ideal for authors or editors who are not familiar with troff arcana. On the one hand, the example in \*(r1 uses a larger variety of troff directives than some casual users might be familiar with. On the other hand, instead of using directives such as .tl to produce first page headings, it suggests that authors or editors should count characters to manually justify the first page heading. .NH 2 "Authors Specify Content Rather Than Issue Directives .IP Another problem with low\-level directives is that authors are not primarily concerned with formatting details. An author needs to indicate things like "this is the document title" or "a new section starts here". Authors rarely think in low\-level formatting terms such as are provided by basic troff directives, e.g. "center the next 3 lines". .NH 2 "ms Macros Are Not Designed For RFCs .IP Macros provide a mechanism for authors to specify type of content rather than formatting details. However, use of the ms macro package is not ideal for production of RFCs and Internet\-Drafts as that macro package was not designed for the specific document format described in \*(r1. Use of some high\-level ms macros results in text which violates some provisions of the \*(r1 format, while other ms macros are unusable due to differences between RFC document format and the types of documents that the ms package was designed to produce. There are also implementation differences in different versions of "ms" macro packages. Finally, it is the ms macro package which has stymied the RFC Editor's attempts to get a form feed character at the end of each page \*(r1, .RR I 1543 .tm RFC 1543 reference is intentional. \&. .NH 2 "RFC-specific Macros .IP This memo describes use of a macro package which is designed specifically for production of RFCs and Internet\-Drafts, which provides a high\-level abstraction to insulate authors and editors from many troff details and frees authors and editors from tedium such as counting characters. .NH 1 "Requirement Levels .IP The key words .\" "MUST", \" 1 .\" "MUST\ NOT", \" 2 .\" "REQUIRED", \" 3 .\" "SHALL", \" 4 .\" "SHALL\ NOT", \" 5 "SHOULD", \" 6 "SHOULD\ NOT" \", \" 7 and "RECOMMENDED" \", \" 8 .\" "MAY" \" 9 .\" "OPTIONAL" \" 10 in this document are to be interpreted as described in .BR N 14 \&. .NH 1 "Processing .IP Production of a document using troff and a macro package proceeds in several stages: .NL .LI A mixture of free\-form text, processing directives, and material describing non\-textual content (tables, diagrams, etc.) is generated by the author. .LI Preprocessors .IR CSTR49 r6 Lesk, M. E., "TBL \- A Program for Setting Tables", Bell Laboratories Computing Science Technical Report #49, Murray Hill, New Jersey, 1976. .IE , .IR CSTR114 s0 Bentley, Jon L. and Kernighan, Brian W., "Grap \- A Language for Typesetting Graphs Tutorial and User Manual", Computing Science Technical Report No.114, AT&T Bell Laboratories, Murray Hill, New Jersey, 1991. .IE , .IR CSTR116 r5 Kernighan, Brian W., "Pic \- A Graphics Language for Typesetting User Manual", Computing Science Technical Report No.116, AT&T Bell Laboratories, Murray Hill, New Jersey, 1991. .IE , .IR CSTR122 r9 Bentley, Jon L., Jelinski, Lynn W., and Kernighan, Brian W., "Chem \- A Program for Typesetting Chemical Diagrams: User Manual", Computing Science Technical Report No.122, AT&T Bell Laboratories, Murray Hill, New Jersey, 1992. .IE , .IR eqn r8 Kernighan, Brian W, and Cherry, Lorinda L., "A System for Typesetting Mathematics", Communications of the ACM 18, 182\-193, 1975. .IE , .IR CSTR142 r7 Bentley, Jon L. "DFORMAT \- A Program for Typesetting Data Formats", Computing Science Technical Report No.142, AT&T Bell Laboratories, Murray Hill, New Jersey, 1988. .IE \& may be used to transform descriptions of tables, diagrams, etc. .LI A formatter transforms instructions and other input into a formatted document according to rules corresponding to the desired document format. .LI Some postprocessing may take place to repaginate output and to make final adjustments to the output format. .LE .IP Tools, e.g.\& .IR make Feldman, S. I., "Make \(em A Program for Maintaining Computer Programs", 1978, in "UNIX TIME\-SHARING SYSTEM (VOLUME\ 2) : UNIX Programmer's Manual", Holt, Rinehart, & Winston, 1979 .IE , are available to automate the preprocessor, formatter, and postprocessing portions of document processing, freeing the author to concentrate on the document content. .NH 1 "Input Format .IP Input consists of text to be formatted, directives that specify formatting parameters and actions, and special sequences that provide access to saved strings and numbers. Directives consist of a line beginning with a period (also known as "dot"). The dot may be followed by space characters, and then a named directive. The name consists of one or more printing characters. Many directives also take arguments, which are space\-separated strings of characters. Unless directed otherwise, input is collected and formed into paragraphs without regard to line breaks in the input. Input text consisting of the lines: .DS L \&.IP All bad precedents begin with justifiable measures. \e" Julius Caesar \&.\e" This is a comment. A strong conviction that something must be done is the parent of many bad measures. \e" Daniel Webster Any excuse will serve a tyrant. \e" Aesop .DE .IP is formatted into an indented paragraph which looks like: .IP All bad precedents begin with justifiable measures. \" Julius Caesar .\" This is a comment. A strong conviction that something must be done is the parent of many bad measures. \" Daniel Webster Any excuse will serve a tyrant. \" Aesop .IP The character sequence \e" introduces a comment which continues to the end of the line. If an entire line is a comment, starting the line with a dot followed by the comment ensures that extra space does not appear in the output. Authors should be careful about use of the backslash, which is an escape character that introduces special sequences. If it is necessary to have a backslash appear in the formatted output, the sequence \ee, i.e. a backslash followed by a lower\-case letter e, will produce it. Unescaped backslashes followed by double quotes have been known to cause important text to vanish from published RFCs. .NH 1 Specifics .NH 2 "Loading the RFC Macros .IP The first directive might be the line: .DS L \&.so tmac.rfc .DE .IP That directs the processor to read the contents of a file named "tmac.rfc", which contains the macros that describe the RFC format, holds boilerplate text, and provides convenience functions. .IP Alternate methods of using the macros might be available: .NL .LI the file tmac.rfc can be specified on the command line before the file with source content .LI the rfc macros may have been locally installed in a manner that permits use of a command\-line \-mrfc argument. .LE .NH 2 "Specifying the Document Particulars .IP Each RFC or Internet\-Draft has a title, one or more authors, etc. These are specified with directives. .NH 3 "Titles, Long and Short" s1 .IP The TL directive, as in .DS L \&.TL "Writing Internet\-Drafts and Requests For Comments using troff and\e \e& nroff .DE .IP specifies the document title. The double\-quote causes the remainder of the (logical) line to be taken as a single argument to the TL macro; otherwise each space character would be taken as an argument separator. The backslash at the end of the first line escapes the end\-of\-line, allowing the line to effectively continue with the contents of the second line. Escape sequences are discussed in detail in \*(r2. There is a short title (ST) macro which is used to specify a short version of the document title for use in page headings. For this document, that was specified as: .DS L \&.ST "Writing I\e\-Ds and RFCs using troff .DE .IP Note also that a backslash character appears before the hyphen; that causes the hyphen to be interpreted as a normal text hyphen rather than as an indication of a possible hyphenation (line\-breaking) point. When a document is formatted as PostScript, a pdfmark entry is created to indicate the document (long) title. As troff escape sequences are not recognized by PostScript interpreters, the long title should not contain any troff escape sequences, including escaped hyphens. As the short title isn't used by pdfmark entries, that restriction doesn't apply to it. .NH 3 "RFC or Draft Version Number" s2 .IP RFCs have an RFC number assigned by the RFC Editor; Internet\-Drafts have a version number. The number is specified with the NU macro or by setting a register with a command\-line argument as described in Appendix A: a negative number is interpreted as an incremental version number for a draft; \-1 for draft version \-00, \-2 for draft version \-01, etc. A positive number is interpreted as an RFC number and SHOULD only be assigned by the RFC Editor. A zero value is treated like an RFC, but prints XXXX where an RFC number would appear. .NH 3 "Document Category (RFCs)" s3 .IP RFCs have a category; one of Experimental, Informational, Standards Track, or Best Current Practice .BR I 9 .tm boilerplate changes do not affect reference to BCP 9 \&. The category is specified as the argument to the CA macro; that macro directive need only be supplied for RFCs (if supplied in drafts it shows as Intended status in the first page heading) .NR ID r4 "Guidelines to Authors of Internet\-Drafts", March 2005, ftp://ftp.ietf.org/ietf/1id\-guidelines.txt .NE \&. .NH 3 "Updated and Obsoleted RFCs" s4 .IP Some RFCs update or obsolete earlier RFCs. If an RFC is updated by the document, the number of the updated RFC should be specified as the argument to an UP macro. Similarly, an obsoleted RFC is indicated by an argument to an OB macro. Multiple UP and OB macros may be used to indicate that multiple RFCs are updated or obsoleted. .NH 3 "Internet-Draft File Name" s5 .IP An Internet\-Draft has a file name used for retrieval; the base file name (without the trailing hyphen and version number suffix) is specified as the argument to the FN macro; the FN macro is not necessary (is ignored) for RFCs. The file name may contain only lower\-case letters, digits, and hyphens \*(r4. .NH 3 "Authors or Editors" s6 .IP An Internet\-Draft or RFC may have up to five authors specified. Information for each author may be specified via the AU macro. The macro takes 9 arguments: .TS H lw(0.8i) cw(5.7i). Argument Description .\" N.B. the following trick ensures consistent nroff/troff spacing for rules across the table .\" the idea is (in troff) to save the vertical position, space down to vertically center the rule (or double rule) in 1P .\" emit the rule, then move to a vertical position 1P below the saved position (to match nroff) .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .TH .T& c l. 1 T{ First initial and surname for first page heading T} 2 T{ First name and/or initials for Author's Address section T} 3 T{ Surname for page footer and Author's Address section T} 4 T{ Gender; one of m (male), f (female), or o (other or indeterminate) T} 5 Internet mailbox 6 Telephone Number 7 Fax Number 8 URL 9 Affiliation .TE .IP The first argument for the first author or editor is used to generate embedded author information when a PDF format document is generated; it should not contain any troff escape sequences. .IP The author's gender was used to customize boilerplate verbiage to accommodate enforcers of political correctness, at least until individual male or female authors were prohibited from submitting Internet\-Drafts with sensible boilerplate. Arguments containing space characters must be enclosed in double quotes. Arguments that are not used must have an empty double quoted string or other zero\-width argument as a placeholder. Optional text following the AU macro line is collected verbatim (without flowing into a paragraph) as the postal address for the author. Similar information can be provided for additional authors by additional AU macro calls. .IP Some documents, notably those produced by IETF Working Groups, are prepared by a Document Editor .BR I 25 .tm mailing list changes do not affect reference to BCP 25 \&. To distinguish an Editor from an Author, use the ED macro instead of the AU macro. There may be multiple Editors. .NH 3 Date s7 .IP The date used for the document heading is normally the current date when formatted. It can be explicitly specified via the DT macro which takes three numeric arguments (4\-digit year, month, and day respectively), or the values may be specified via command\-line arguments as described in Appendix A. .NH 3 "Section Headings and the Table of Contents" s8 .IP An RFC or Internet\-Draft may contain numbered sections. Sections may have subsections, and the section level represents the number of dot\-separated levels. This section of this document has level \n(NS. A long document benefits from a Table of Contents. As sections are specified, the rfc macro package collects information for a Table of Contents. The TC macro takes two arguments. The first specifies the number of pages to reserve for the Table of Contents (zero to omit the table), and the second argument specifies the maximum section level to include in the Table of Contents entries. .IP These parameters may alternatively be specified via command\-line arguments. See Appendix A for details. .ds ix ndependent .NH 3 "Independent vs. IETF Submissions" s9 .IP Internet\-Drafts and RFCs may be products of IETF Working Groups or other IETF entities, or they may be i\*(ix submissions. The macro IS is used to identify i\*(ix submissions, as there is a slight difference in the boilerplate text which accompanies them. The IS macro takes no arguments. .IP Unfortunately, the IETF Secretariat rejects i\*(ix Internet\-Draft submissions that have the i\*(ix submission boilerplate required by the RFC Editor .DR I Instruct draft-rfc-editor-rfc2223bis r0 \& (bottom of page 33), probably because it is not recognized by Henrik Levkowetz' "idnits" program .IR idnits q1 http://ietf.levkowetz.com/tools/idnits/ .IE \&. Therefore, until the IETF Secretariat and the RFC Editor resolve their differences the IS macro SHOULD NOT be used except by the RFC Editor. .NH 3 "Optional Notices" s0 .IP Certain optional notices may be placed at the front of Internet\-Drafts. The ON macro is used to specify one of the following notices via a numeric argument: .TS H lw(0.4i) cw(6.1i). Type Text .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .TH .T& c l. 1 T{ This document may not be modified, and derivative works of it may not be created. This document may only be posted in an Internet\-Draft. T} 2 T{ This document may not be modified, and derivative works of it may not be created, except to publish it as an RFC and to translate it into languages other than English. T} .TE .IP If a second argument is given to the ON macro, it is interpreted as the number of a section that may be extracted. The text is modified to reflect that. For example: .LP \&.ON 1 1.2.3 .IP produces the text: .IP This document may not be modified, and derivative works of it may not be created other than to extract section 1.2.3 as\-is for separate use. This document may only be posted in an Internet\-Draft. .NH 2 "Document Content .IP Having specified preliminary information as described above, the document content may be specified. .NH 3 Abstract t1 .IP The first item that an author might want to provide is the Abstract for the document. It is initiated with the AB macro, which takes no arguments. It collects text until the next macro directive into a paragraph for the document abstract. An abstract is required for an Internet\-Draft; it is optional for an RFC. .NH 3 "Numbered and Unnumbered Sections" t2 .IP Additional document content is usually organized into sections. There are two types of sections: numbered and unnumbered. For the purpose of collecting headings for the Table of Contents, unnumbered sections have a section "level" even though no number appears. A section is initiated with an SH macro for unnumbered sections, or an NH macro for numbered sections. Each macro requires two arguments: the section level and the section heading text. Numbering for numbered sections is computed automatically. The NH macros accepts an optional third argument, to save the generated section number string in a named string; the third argument must be 2 characters suitable as the name of a string. Internal string names used by the rfc macro package always begin with an upper\-case letter; it is generally safe to use a two\-character name that begins with a lower\-case letter which is followed by an upper\-case letter or a digit (troff internally has some strings which are named with two lower\-case letters). .IP When a document is formatted as PostScript, pdfmark entries are made which are intended to create corresponding "Bookmark" entries when a PDF file is produced. The title for the bookmark entry is taken from the section heading, which should not contain any troff special characters (including escaped hyphens). .NH 3 Paragraphs t3 .IP Within sections, text is organized into paragraphs. RFCs and Internet\-Drafts usually use indented block paragraphs like this one; these are introduced with the IP macro. That macro can take two optional arguments: initial unindented text and an indent distance. The defaults are no unindented text and an indent distance of 3 character spaces (0.3 inch). Various units may be used in troff; it is strongly RECOMMENDED that horizontal distances, such as the indent distance, be specified in multiples of 0.1 inch so that nroff\- and troff\-formatted versions of documents maintain the same line and page breaks. .IP Unindented paragraphs are possible via the LP macro. .NH 3 "Special Indentation" t4 .IP Indentation may be controlled with RS and RE macros. The RS macro will increase the indent level by the paragraph indentation increment of 3 character spaces, while the RE macro will reduce indentation by that amount. .NH 3 "Reserving Vertical Space" t5 .IP Sometimes it is necessary to ensure that there is sufficient vertical space before the bottom of the current page for some complex output that cannot easily be handled with a keep or display (see below). The NS macro takes one argument specifying the number of text lines needed. If fewer lines remain on the current page, output will continue at the top of the next page. .NH 3 "Keeps and Displays" t6 .IP Sometimes one has lines of text or non\-textual content which one would like to appear as a group, uninterrupted by page breaks. Such a group is called a "keep" and is specified by preceding the group with the KS macro and following it with a KE macro. Keeps are typically used to fine\-tune formatting; they are rarely required. .IP Keeps will not work with multiple paragraphs (or list items) between KS and KE directives. To force a page break if there is less than a certain amount of vertical space remaining on the current page, use the NS macro directive to reserve space. .IP More complex groupings can be obtained by "displays". Displays are started like keeps, using the DS macro. Display content is not filled into paragraphs; output appears like the input lines except for indentation. The DS macro takes an argument consisting of a single letter which identifies the type of display: .TS H lw(0.4i)1 cw(6.3i). Type Description .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .TH .T& c l. C T{ Each line of text is centered T} B T{ The input lines are read as a block, and the block is centered T} L T{ The display is left\-aligned T} I T{ The display is indented by the amount indicated by an optional second argument (default is 3 character spaces) T} .TE .IP Displays are typically used for block quoted material and for preventing page breaks within non\-textual material such as tables and diagrams. For example, the input: .DS L \&.DS C War is Peace Freedom is Slavery Ignorance is Strength \&.\e" Eric Arthur Blair, a.k.a. George Orwell \&.DE .DE .IP produces output in which each line is centered: .DS C War is Peace Freedom is Slavery Ignorance is Strength .\" Eric Arthur Blair, a.k.a. George Orwell .DE .IP whereas the input: .DS L \&.DS B War can still settle problems, but it can only settle them the wrong way. \e" Bertrand Russell \&.DE .DE .IP produces the text lines as a centered block: .DS B War can still settle problems, but it can only settle them the wrong way. \" Bertrand Russell .DE .IP Sometimes placement of a display, such as one containing a diagram, is not critical. A floating display allows text and non\-floating displays which follow it in the source document to be output before it if it will not fit on the current output page. A floating display begins with a DF macro call, taking the same arguments as DS and ending with a DE macro call. Floating displays are output before the end of the section and subsection in which they are defined in the input, so they cannot appear in the wrong section of the formatted document. .IP Text following a display or keep should be organized as a paragraph, to ensure that the text appears where expected on output and so that page breaks can be adjusted to prevent widows and orphans. .NH 3 Lists t7 .NH 4 "Numbered Lists" t8 .IP The NL macro initializes a numbered list. It takes four optional arguments: .NL .LI a prefix string. The default is an empty string (no prefix). .NS 4P .LI a one\-character numbering format; one of .VL 4 .LI 1 number using Arabic numerals (the default) .LI I number using Roman numbers expressed as upper\-case letters .LI i number using Roman numbers expressed as lower\-case letters .LI A letter with upper\-case letters .LI a letter with lower\-case letters .LE .LI a suffix string. The default is a period. .LI the indent distance (in characters as a dimensionless number) for running list text. A suitable value will depend on the numbering format, length of suffix and/or prefix, and the expected number of items. The default value is the paragraph indent distance. .LE .IP Each list item after the initialization is introduced by the LI (list item) macro. Text following the LI macro line is processed as an indented paragraph with the first line numbered. .IP The most recently started list is terminated with the LE (list end) macro. .IP Lists may be nested up to 9 levels deep. Each level of nesting is indented by the paragraph indent value (3 characters). The list above has a variable list (see description below) inside a numbered list. .NH 4 "Bulleted Lists" t9 .IP A bulleted list is initialized with the BL macro. List items also use the LI macro and the LE macro ends a bulleted list. .IP The input lines: .DS L \&.BL \&.LI first bulleted item \&.LI second bulleted item \&.LE .DE .IP produce the output: .BL .LI first bulleted item .LI second bulleted item .LE .IP The BL macro will accept an optional argument, which is treated as a string to use in place of the default bullet character. .NH 4 "Variable Lists" t0 .IP The VL macro initializes a variable list. Each list item is labeled with a string supplied as an argument on that item's LI macro line. The VL macro takes one optional argument which specifies the indent distance (in characters as a dimensionless number) for running list text. A suitable value will depend on the expected lengths of list item labels. The default value is the paragraph indent distance. The LE macro terminates a variable list. .NH 3 References u1 .IP Internet\-Drafts and RFCs contain two types of references: normative references and informative references. Citations for the reference material appear near the end of the document and are indicated by a bracketed tag within the document text like this: \*(r1. Macros are provided to automatically number and format normative and informative references in the style used in this document. The reference tags consist of the letter N (for normative references) or I (for informative references), followed by a sequential number within each series, optionally followed by a dot and a string supplied as an argument to the NR macro for normative references, IR for informative references. A second argument may be supplied to save the generated reference tag in a named string; the second argument must be 2 characters suitable as the name of a string. Internal string names used by the rfc macro package always begin with an upper\-case letter; it is generally safe to use a two\-character name that begins with a lower\-case letter which is followed by an upper\-case letter or a digit (troff internally has some strings which are named with two lower\-case letters). The first normative reference in this document could have been specified by the lines: .DS L \&.NR RFC2223 r1 Postel, J. and J. Reynolds, "Instructions to RFC Authors", RFC\e\ 2223, October 1997. \&.NE .DE .IP For references to RFCs, one can simply copy and paste the text made available by the RFC Editor in the file rfc\-ref.txt, as has been done in this example (the actual reference text was on a single input line, though that is not required, and the backslash preceding the space after "RFC" prevents lines being broken at that space, i.e. within the RFC document number). The reference text follows the NR or IR macro line and will be suitably formatted and placed in the Normative References or Informative References section of the generated document. The reference text is ended with an NE or IE macro. .IP The bracketed reference string appears in the text at the place where the NR/NE or IR/IE macros are placed, while the actual reference citation text is saved for output in unnumbered Normative References and Informative References sections. No space appears after the bracketed reference, so a list of such references may appear with comma separators by simply placing a line containing a comma between reference macro groups. If a bracketed reference appears at the end of a sentence, the period marking the end of the sentence must be provided in the input after the NE or IE macro line. However, a line beginning with a dot is normally interpreted as a directive; to prevent that, the line should begin with the two character sequence \e& preceding the period. That sequence represents a zero\-width non\-printing space which prevents interpretation of the line as a directive without affecting the appearance of the output. .IP The reference tag (including the brackets) generated by the example above is saved in the troff string named r1, which can be used to refer to the same reference. That reference tag can be made to subsequently appear in the document text via a reference to the saved troff string, viz. the character sequence \e*(r1. .IP References to RFCs by number or via numeric reference to the corresponding BCP, STD, or FYI series number can be generated by using the rfcref preprocessor. That preprocessor takes input like: .DS L \&.RR N 2223 r1 .DE .IP and generates the corresponding reference text and NR/NE or IR/IE macro directives. That involves a little less manual work for authors; there is no need to copy reference citation text and there is no end\-of\-reference directive. .IP Four preprocessor directives are recognized: .TS H lw(0.9i) cw(1.5i). Directive Document Series .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .TH .T& c c. BR BCP FR FYI SR STD RR RFC .TE .IP Each directive takes two or three arguments: .NL .LI a single letter, I or N, to indicate an informative or normative reference, respectively .LI the document series number .LI (optional) a string name for saving the reference tag .LE .IP Note that some STD documents map to multiple RFC numbers, and that some STD document series numbers are either reserved for future use or are no longer in use. .IP The rfcref preprocessor also checks whether documents have been updated or obsoleted, and issues suitable warnings. .IP Another preprocessor, idref, performs a similar function for references to Internet\-Drafts. It converts a directive DR to an Internet\-Draft reference, given arguments to indicate reference type (I or N as above), a reference tag string, the draft file name (without file type or version number suffixes), and an optional string name for saving the complete reference tag. .NH 3 "MIB modules, etc." u2 .IP When a MIB module or similar entity is defined and there is a limitation notice (via the ON macro), there may need to be a separate copyright notice placed in the part to be extracted per .BR N 78 r3 \&. The IB macro may be called at the appropriate section to generate the properly\-formatted boilerplate text. The mandatory first argument to the IB macro selects the type of statement from the ones permitted by \*(r3, and the optional second argument permits specifying something other than "MIB module". An optional third argument may be used to specify a prefix to the statement, an optional fourth argument may be used to specify an indent other than paragraph indent, and an optional fifth argument may be used for a suffix. Unused arguments may be specified as empty strings or other zero\-width items. The types are: .TS H lw(0.4i) cw(6.1i). Type Text .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .TH .T& c l. 1 T{ Copyright\0\0\(co\0\0The Internet Society (2005). This version of this MIB module is part of RFC XXXX; see the RFC itself for full legal notices. T} 2 T{ Copyright\0\0\(co\0\0The Internet Society (2005). The initial version of this MIB module was published in RFC XXXX; for full legal notices see the RFC itself. Supplementary information may be available on http://www.ietf.org/copyrights/ianamib.html. T} .TE .IP The correct year is used, and when an RFC number is assigned by the RFC Editor, the RFC number will appear in place of XXXX. As noted above, alternate text may be substituted for "MIB module". .NH 3 "Document Appendices" u3 .IP Appendices appear like numbered sections, except that the first\-level consists of upper\-case letters rather than numbers. Each appendix to appear in the document should be introduced with the AP macro, which causes such numbering to take place. The AP macro requires one argument, the appendix heading text. An optional second argument may be specified as a string name for saving the appendix, as with numbered sections. Subdivided sections within an appendix can be introduced with second\-, third\-level, etc. numbering via NH macros as with document body sections. .NH 2 "End Matter" u4 .IP At the very end of the input file describing the document, the author should place an EM macro directive. That causes output of references, author's address (or authors' addresses), and IPR boilerplate sections. If a TC macro was provided at the beginning of the document input with a non\-zero first argument, or if the document is more than 15 pages in length, a Table of Contents is also produced. .\" additional sections here .\" Contributors .\" .NH 1 Contributors .\" .IP .\" Acknowledgments .NH 1 Acknowledgments .IP The author gratefully acknowledges the discussions of RFC formatting on the rfc\-interest mailing list. .IP The format for references was inspired by Keith Moore's draft subsequently published as .RR I 3834 \&. .\" Security considerations .NH 1 "Security Considerations .IP No security considerations are addressed by this memo. .\" Internationalization considerations .NH 1 "Internationalization Considerations .IP This memo raises no new internationalization considerations. .\" IANA considerations .if \nN<0 \{ \ .NH 1 "IANA Considerations .IP This memo adds no new IANA considerations. .\} .\" Appendixes .AP Esoterica .NH 2 "Troff vs. Nroff .IP RFCs and Internet\-Drafts are produced as text documents. It is sometimes desirable to produce a formatted version for improved rendition of diagrams, etc. The rfc macro package has been designed so that troff formatted output resembles the text version as closely as possible; it utilizes a monospaced font for text, does not embolden section headings (unlike the ms macro package), and centers each page within 8.5 by 11 inch page boundaries. Other than improved appearance of non\-textual matter, troff and nroff versions of documents produced with the rfc macro package should appear nearly identical after postprocessing, including page and line breaks. One subtlety is that centered text with an odd number of characters is offset left or right in nroff output, whereas it is truly centered in troff output. Output processed with nroff for text production includes a form feed character after each page (the "fix.pl" script specified in \*(r1 is not necessary). .IP Separate processing can be performed by troff and nroff by using nroff/troff conditionals, e.g.: .DS L \&.ie t \e{ \e \&.\e} \&.el \e{ \e \&.\e} .DE .IP For a more complete example, consider: .DS B .ie t \{ \ .\" Creator: dot version 1.14 (Tue Sep 7 21:59:34 UTC 2004) .\" For: (root) root .\" Title: references .\" save point size and font .nr .S \n(.s .nr DF \n(.f .PS 4.95833 5.50000 # to change drawing size, multiply the width and height on the .PS line above and the number on the two lines below (rounded to the nearest integer) by a scale factor .nr SF 4958 scalethickness = 4958 # don't change anything below this line in this drawing # non-fatal run-time pic version determination, version 2 boxrad=2.0 # will be reset to 0.0 by gpic only scale=1.0 # required for comparisons # boxrad is now 0.0 in gpic, else it remains 2.0 # dashwid is 0.1 in 10th Edition, 0.05 in DWB 2 and in gpic # fillval is 0.3 in 10th Edition (fill 0 means black), 0.5 in gpic (fill 0 means white), undefined in DWB 2 # fill has no meaning in DWB 2, gpic can use fill or filled, 10th Edition uses fill only # DWB 2 doesn't use fill and doesn't define fillval # reset works in gpic and 10th edition, but isn't defined in DWB 2 # DWB 2 compatibility definitions if boxrad > 1.0 && dashwid < 0.075 then X fillval = 1; define fill Y Y; define solid Y Y; define reset Y scale=1.0 Y; X reset # set to known state # GNU pic vs. 10th Edition d\(e'tente if fillval > 0.4 then X define setfillval Y fillval = 1 - Y; define bold Y thickness 2 Y; # if you use gpic and it barfs on encountering "solid", # install a more recent version of gpic or switch to DWB or 10th Edition pic; # sorry, the groff folks changed gpic; send any complaint to them; X else Z define setfillval Y fillval = Y; define bold Y Y; define filled Y fill Y; Z # arrowhead has no meaning in DWB 2, arrowhead = 7 makes filled arrowheads in gpic and in 10th Edition # arrowhead is undefined in DWB 2, initially 1 in gpic, 2 in 10th Edition arrowhead = 7 # not used by graphviz # GNU pic supports a boxrad variable to draw boxes with rounded corners; DWB and 10th Ed. do not boxrad = 0 # no rounded corners in graphviz # GNU pic supports a linethick variable to set line thickness; DWB and 10th Ed. do not linethick = 0; oldlinethick = linethick # .PS w/o args causes GNU pic to scale drawing to fit 8.5x11 paper; DWB does not # maxpsht and maxpswid have no meaning in DWB 2.0, set page boundaries in gpic and in 10th Edition # maxpsht and maxpswid are predefined to 11.0 and 8.5 in gpic maxpsht = 5.500000 maxpswid = 4.958333 Dot: [ define attrs0 % %; define unfilled % %; define rounded % %; define diagonals % % setfillval 0.000000 setfillval 0.000000 .ft R .ps 14*\n(SFu/4958u # a { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (0.87500,5.25000); { define attrs2 % % setfillval 0.000000 "a" at (0.86806,5.24537); } linethick = oldlinethick } linethick = oldlinethick # c { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (0.37500,4.25000); { define attrs2 % % setfillval 0.000000 "c" at (0.36806,4.24537); } linethick = oldlinethick } linethick = oldlinethick # a -> c P0: (0.75000,5.00000) P1: (0.73293,4.96587) P2: (0.71511,4.93033) P3: (0.69662,4.89363) P4: (0.67756,4.85600) P5: (0.65799,4.81771) P6: (0.63800,4.77900) P7: (0.61768,4.74012) P8: (0.59711,4.70133) P9: (0.57637,4.66287) P10: (0.55556,4.62500) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (0.59722,4.61111) P1: (0.50000,4.50000) P2: (0.51389,4.65278) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # d { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (1.37500,4.25000); { define attrs2 % % setfillval 0.000000 "d" at (1.37500,4.24537); } linethick = oldlinethick } linethick = oldlinethick # a -> d P0: (1.00000,5.00000) P1: (1.01707,4.96587) P2: (1.03489,4.93033) P3: (1.05337,4.89363) P4: (1.07244,4.85600) P5: (1.09201,4.81771) P6: (1.11200,4.77900) P7: (1.13232,4.74012) P8: (1.15289,4.70133) P9: (1.17363,4.66287) P10: (1.19444,4.62500) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (1.23611,4.65278) P1: (1.25000,4.50000) P2: (1.15278,4.61111) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # q { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (3.40278,5.25000); { define attrs2 % % setfillval 0.000000 "q" at (3.40278,5.24537); } linethick = oldlinethick } linethick = oldlinethick # r { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (2.90278,4.25000); { define attrs2 % % setfillval 0.000000 "r" at (2.90278,4.24537); } linethick = oldlinethick } linethick = oldlinethick # q -> r P0: (3.27778,5.00000) P1: (3.26071,4.96587) P2: (3.24289,4.93033) P3: (3.22440,4.89363) P4: (3.20533,4.85600) P5: (3.18576,4.81771) P6: (3.16578,4.77900) P7: (3.14546,4.74012) P8: (3.12489,4.70133) P9: (3.10415,4.66287) P10: (3.08333,4.62500) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (3.12500,4.61111) P1: (3.02778,4.50000) P2: (3.04167,4.65278) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # s { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (3.90278,4.25000); { define attrs2 % % setfillval 0.000000 "s" at (3.90278,4.24537); } linethick = oldlinethick } linethick = oldlinethick # q -> s P0: (3.52778,5.00000) P1: (3.54485,4.96587) P2: (3.56267,4.93033) P3: (3.58115,4.89363) P4: (3.60022,4.85600) P5: (3.61979,4.81771) P6: (3.63978,4.77900) P7: (3.66010,4.74012) P8: (3.68067,4.70133) P9: (3.70140,4.66287) P10: (3.72222,4.62500) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (3.76389,4.65278) P1: (3.77778,4.50000) P2: (3.68056,4.61111) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # h { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (0.37500,3.25000); { define attrs2 % % setfillval 0.000000 "h" at (0.36806,3.24537); } linethick = oldlinethick } linethick = oldlinethick # c -> h P0: (0.37500,4.00000) P1: (0.37500,3.96626) P2: (0.37500,3.93178) P3: (0.37500,3.89662) P4: (0.37500,3.86089) P5: (0.37500,3.82465) P6: (0.37500,3.78800) P7: (0.37500,3.75101) P8: (0.37500,3.71378) P9: (0.37500,3.67638) P10: (0.37500,3.63889) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (0.43056,3.63889) P1: (0.37500,3.50000) P2: (0.33333,3.63889) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # t { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (2.90278,3.25000); { define attrs2 % % setfillval 0.000000 "t" at (2.89583,3.24537); } linethick = oldlinethick } linethick = oldlinethick # r -> t P0: (2.90278,4.00000) P1: (2.90278,3.96626) P2: (2.90278,3.93178) P3: (2.90278,3.89662) P4: (2.90278,3.86089) P5: (2.90278,3.82465) P6: (2.90278,3.78800) P7: (2.90278,3.75101) P8: (2.90278,3.71378) P9: (2.90278,3.67638) P10: (2.90278,3.63889) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (2.95833,3.63889) P1: (2.90278,3.50000) P2: (2.86111,3.63889) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # i { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (1.37500,3.25000); { define attrs2 % % setfillval 0.000000 "i" at (1.37500,3.24537); } linethick = oldlinethick } linethick = oldlinethick # d -> i P0: (1.37500,4.00000) P1: (1.37500,3.96626) P2: (1.37500,3.93178) P3: (1.37500,3.89662) P4: (1.37500,3.86089) P5: (1.37500,3.82465) P6: (1.37500,3.78800) P7: (1.37500,3.75101) P8: (1.37500,3.71378) P9: (1.37500,3.67638) P10: (1.37500,3.63889) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (1.43056,3.63889) P1: (1.37500,3.50000) P2: (1.33333,3.63889) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # j { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (2.25000,2.25000); { define attrs2 % % setfillval 0.000000 "j" at (2.25000,2.24537); } linethick = oldlinethick } linethick = oldlinethick # d -> j P0: (1.56944,4.00000) P1: (1.59937,3.95713) P2: (1.63056,3.91200) P3: (1.66257,3.86488) P4: (1.69500,3.81600) P5: (1.72743,3.76562) P6: (1.75944,3.71400) P7: (1.79063,3.66138) P8: (1.82056,3.60800) P9: (1.84882,3.55413) P10: (1.87500,3.50000) P11: (1.91167,3.41514) P12: (1.94667,3.32778) P13: (1.98000,3.23875) P14: (2.01167,3.14889) P15: (2.04167,3.05903) P16: (2.07000,2.97000) P17: (2.09667,2.88264) P18: (2.12167,2.79778) P19: (2.14500,2.71625) P20: (2.16667,2.63889) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 move to P10; line attrs0 to P11 then to P12 move to P12; line attrs0 to P13 then to P14 move to P14; line attrs0 to P15 then to P16 move to P16; line attrs0 to P17 then to P18 move to P18; line attrs0 to P19 then to P20 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (2.20833,2.63889) P1: (2.19444,2.50000) P2: (2.12500,2.62500) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # u { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (3.90278,3.25000); { define attrs2 % % setfillval 0.000000 "u" at (3.89583,3.24537); } linethick = oldlinethick } linethick = oldlinethick # s -> u P0: (3.90278,4.00000) P1: (3.90278,3.96626) P2: (3.90278,3.93178) P3: (3.90278,3.89662) P4: (3.90278,3.86089) P5: (3.90278,3.82465) P6: (3.90278,3.78800) P7: (3.90278,3.75101) P8: (3.90278,3.71378) P9: (3.90278,3.67638) P10: (3.90278,3.63889) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (3.95833,3.63889) P1: (3.90278,3.50000) P2: (3.86111,3.63889) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # w { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (4.58333,2.25000); { define attrs2 % % setfillval 0.000000 "w" at (4.57639,2.24537); } linethick = oldlinethick } linethick = oldlinethick # s -> w P0: (4.11111,4.00000) P1: (4.14103,3.95713) P2: (4.17211,3.91200) P3: (4.20386,3.86488) P4: (4.23578,3.81600) P5: (4.26736,3.76562) P6: (4.29811,3.71400) P7: (4.32753,3.66138) P8: (4.35511,3.60800) P9: (4.38036,3.55413) P10: (4.40278,3.50000) P11: (4.43407,3.41514) P12: (4.46144,3.32778) P13: (4.48515,3.23875) P14: (4.50544,3.14889) P15: (4.52257,3.05903) P16: (4.53678,2.97000) P17: (4.54832,2.88264) P18: (4.55744,2.79778) P19: (4.56440,2.71625) P20: (4.56944,2.63889) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 move to P10; line attrs0 to P11 then to P12 move to P12; line attrs0 to P13 then to P14 move to P14; line attrs0 to P15 then to P16 move to P16; line attrs0 to P17 then to P18 move to P18; line attrs0 to P19 then to P20 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (4.61111,2.63889) P1: (4.58333,2.50000) P2: (4.52778,2.63889) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # k { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (1.25000,2.25000); { define attrs2 % % setfillval 0.000000 "k" at (1.24306,2.24537); } linethick = oldlinethick } linethick = oldlinethick # h -> k P0: (0.59722,3.00000) P1: (0.63093,2.96211) P2: (0.66522,2.92356) P3: (0.69985,2.88450) P4: (0.73456,2.84511) P5: (0.76910,2.80556) P6: (0.80322,2.76600) P7: (0.83668,2.72661) P8: (0.86922,2.68756) P9: (0.90060,2.64900) P10: (0.93056,2.61111) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (0.97222,2.63889) P1: (1.02778,2.50000) P2: (0.90278,2.56944) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # v { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (3.31944,2.25000); { define attrs2 % % setfillval 0.000000 "v" at (3.31944,2.24537); } linethick = oldlinethick } linethick = oldlinethick # t -> v P0: (3.01389,3.00000) P1: (3.02678,2.96589) P2: (3.04033,2.93044) P3: (3.05439,2.89400) P4: (3.06878,2.85689) P5: (3.08333,2.81944) P6: (3.09789,2.78200) P7: (3.11228,2.74489) P8: (3.12633,2.70844) P9: (3.13989,2.67300) P10: (3.15278,2.63889) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (3.20833,2.65278) P1: (3.20833,2.50000) P2: (3.11111,2.61111) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # i -> k P0: (1.34722,3.00000) P1: (1.34306,2.96626) P2: (1.33889,2.93178) P3: (1.33472,2.89662) P4: (1.33056,2.86089) P5: (1.32639,2.82465) P6: (1.32222,2.78800) P7: (1.31806,2.75101) P8: (1.31389,2.71378) P9: (1.30972,2.67638) P10: (1.30556,2.63889) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (1.34722,2.62500) P1: (1.27778,2.50000) P2: (1.26389,2.63889) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # u -> v P0: (3.75000,3.00000) P1: (3.73253,2.96588) P2: (3.71356,2.93033) P3: (3.69325,2.89363) P4: (3.67178,2.85600) P5: (3.64931,2.81771) P6: (3.62600,2.77900) P7: (3.60203,2.74012) P8: (3.57756,2.70133) P9: (3.55275,2.66288) P10: (3.52778,2.62500) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (3.56944,2.59722) P1: (3.45833,2.50000) P2: (3.48611,2.63889) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # l { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (2.25000,1.25000); { define attrs2 % % setfillval 0.000000 "l" at (2.25000,1.24537); } linethick = oldlinethick } linethick = oldlinethick # k -> l P0: (1.50000,2.00000) P1: (1.53790,1.96210) P2: (1.57656,1.92344) P3: (1.61588,1.88412) P4: (1.65578,1.84422) P5: (1.69618,1.80382) P6: (1.73700,1.76300) P7: (1.77815,1.72185) P8: (1.81956,1.68044) P9: (1.86112,1.63888) P10: (1.90278,1.59722) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (1.93056,1.63889) P1: (2.00000,1.50000) P2: (1.86111,1.56944) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # j -> l P0: (2.25000,2.00000) P1: (2.25000,1.96626) P2: (2.25000,1.93178) P3: (2.25000,1.89662) P4: (2.25000,1.86089) P5: (2.25000,1.82465) P6: (2.25000,1.78800) P7: (2.25000,1.75101) P8: (2.25000,1.71378) P9: (2.25000,1.67637) P10: (2.25000,1.63889) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (2.30556,1.63889) P1: (2.25000,1.50000) P2: (2.20833,1.63889) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # x { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (3.31944,1.25000); { define attrs2 % % setfillval 0.000000 "x" at (3.31250,1.24537); } linethick = oldlinethick } linethick = oldlinethick # w -> x P0: (4.26389,2.00000) P1: (4.21687,1.96171) P2: (4.16778,1.92200) P3: (4.11701,1.88112) P4: (4.06500,1.83933) P5: (4.01215,1.79688) P6: (3.95889,1.75400) P7: (3.90562,1.71096) P8: (3.85278,1.66800) P9: (3.80076,1.62537) P10: (3.75000,1.58333) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (3.77778,1.54167) P1: (3.63889,1.50000) P2: (3.72222,1.62500) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # v -> x P0: (3.31944,2.00000) P1: (3.31944,1.96626) P2: (3.31944,1.93178) P3: (3.31944,1.89662) P4: (3.31944,1.86089) P5: (3.31944,1.82465) P6: (3.31944,1.78800) P7: (3.31944,1.75101) P8: (3.31944,1.71378) P9: (3.31944,1.67637) P10: (3.31944,1.63889) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (3.37500,1.63889) P1: (3.31944,1.50000) P2: (3.27778,1.63889) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # z { define attrs1 % % box attrs1 wid 0.75000 ht 0.50000 at (2.77778,0.25000); { define attrs2 % % setfillval 0.000000 "z" at (2.77083,0.24537); } linethick = oldlinethick } linethick = oldlinethick # l -> z P0: (2.38889,1.00000) P1: (2.40596,0.96588) P2: (2.42378,0.93033) P3: (2.44226,0.89363) P4: (2.46133,0.85600) P5: (2.48090,0.81771) P6: (2.50089,0.77900) P7: (2.52121,0.74012) P8: (2.54178,0.70133) P9: (2.56251,0.66287) P10: (2.58333,0.62500) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (2.62500,0.63889) P1: (2.65278,0.50000) P2: (2.54167,0.59722) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick # x -> z P0: (3.18056,1.00000) P1: (3.16349,0.96588) P2: (3.14567,0.93033) P3: (3.12718,0.89363) P4: (3.10811,0.85600) P5: (3.08854,0.81771) P6: (3.06856,0.77900) P7: (3.04824,0.74012) P8: (3.02767,0.70133) P9: (3.00693,0.66287) P10: (2.98611,0.62500) move to P0; line attrs0 to P1 then to P2 move to P2; line attrs0 to P3 then to P4 move to P4; line attrs0 to P5 then to P6 move to P6; line attrs0 to P7 then to P8 move to P8; line attrs0 to P9 then to P10 { define attrs1 % % define attrs1 % solid % oldlinethick = linethick;linethick = 1 * scalethickness / 4958 P0: (3.02778,0.59722) P1: (2.91667,0.50000) P2: (2.94444,0.63889) move to P0; line attrs1 to P1 move to P1; line attrs1 to P2 move to P2; line attrs1 to P0 } linethick = oldlinethick ] .PE .\" restore point size and font .ps \n(.S .ft \n(DF .\} .el \{ \ .PS 4.95833 5.50000 box invis ht 5.5 wid 5.0 "(see PostScript or PDF versions for diagram)" .PE .\} .PS maxpsht = 9.0 maxpswid = 7.2 reset .PE .DE .IP Diagrams imported from some sources which generate pic may require a reset, and in some cases setting of pic variables such as maxpsht and maxpswid. .IP To conform page breaks between troff\- and nroff\-generated documents, the height of troff\- and nroff\-produced output should be the same. In the example above, that is implemented with an invisible pic box in the nroff\-processed version which contains the text referring to the troff\-formatted versions. .IP Some implementations fake text formatting with "troff\ \-a" or "troff\ \-N" rather than a true nroff. That generally works poorly, particularly if tables, diagrams, etc. are included in the document. .IP Some troff implementations can produce PostScript directly; others require a separate postprocessor. PostScript produced by some troff implementations is not amenable to postprocessing to repaginate (relocate the table of contents). .NS 10P .NH 2 "Output Adjustments .IP Formatting may be adjusted by setting registers using command\-line arguments \*(r2. Register names and default values are: .TS H lw(0.4i) lw(1.3i) lw(4.4i). Name Default Value Function .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .TH .T& c l l. C 0 (zero) T{ Table of Contents length (pages) T} D T{ Current day of month T} T{ Day of month used as publication date. Overridden by DT macro. T} H 2 T{ Highest section heading level to include in Table of Contents T} I 0.3i T{ Paragraph indent increment. Each character is 0.1i wide. T} L 7.2i T{ Text line length. Each character is 0.1i wide. The default value provides 72 characters per line and may not be exceeded. T} M T{ Current month T} T{ Month number (January = 1) used as publication date. Overridden by DT macro. T} N 0 (zero) T{ RFC or Draft version number (negative for drafts). Overrides NU macro if non\-zero. T} O 2 T{ Minimum number of continued running text lines at bottom of page (anything less is considered an orphan). T} P 12 T{ Text point size (troff). T} Q 58 T{ Printed lines per page. The default value is the maximum permitted. T} R T{ for centered text (troff) T} T{ Page offset for odd\-numbered (recto) pages. Always zero for nroff (text output). T} S 1P T{ Interparagraph vertical space. The default is equivalent to one text line. For nroff/troff consistency, the value should be an integral multiple of 1P. T} T T{ for centered text (troff) T} T{ Top margin. Always zero for nroff (text output). T} V T{ for centered text (troff) T} T{ Page offset for even\-numbered (verso) pages. Always zero for nroff (text output). T} W 2 T{ Minimum number of continued running text lines at top of page (anything less is considered a widow). T} X 8.5i T{ Physical page width (troff). T} Y T{ Current year T} T{ 4\-digit year number used as publication date. Overridden by DT macro. T} Z 11i T{ Physical page height (troff). T} .TE .NH 3 "Formatting for Specific Paper Sizes .IP By default, output processed by troff (as distinct from text output produced by nroff) is formatted for economical ANSI standard A (8.5\ x\ 11 inches) .IR ANSI151 American National Standards Institute (ANSI), "Bond Papers and Index Bristols\ \- Common Sheet Sizes", ANSI INCITS 151\-1987 (R2002) .IE \& paper, with the printed content centered on each page. Output may instead be formatted for other paper sizes by setting troff registers listed above (as these all have one\-letter names, they can be set by command\-line arguments; they SHOULD NOT be set in the source file as that would adversely affect output produced from that source file, e.g. by the RFC Editor). For example, to produce output formatted for ISO .IR ISO216 International Organization for Standardization (ISO), "Writing paper and certain classes of printed matter\ \-\- Trimmed sizes\ \-\- A and B series", ISO\ 216:1975 .IE \& A4 paper, with a 20mm margin for hole punches for ring binder filing, registers X, Z, R, and V would be set with command\-line arguments \-rX21c \-rZ29.7c \-rR2c \-rV0.712c. .NH 2 "Tips and Tricks .IP Handling non\-textual material is simplified by using preprocessors. However, there are some subtleties that can cause frustration for authors. Some tips regarding preprocessors and a few tricks to ensure satisfactory formatting follow. .NH 3 "Mathematics and Chemistry .IP While eqn \*(r8 is capable of setting complex equations, many symbols cannot be adequately represented in plain text. so, while .EQ x = f(y/2) + y/2 .EN can be approximated, complex mathematics cannot be represented well in plain text. Subscripts and superscripts pose problems, and for that reason chemical formulae cannot be represented well except for trivial cases. Chem \*(r9 also tends to emit excess vertical space before a formula not containing a carbon ring and tends to screw up subsequent diagrams unless at least the first diagram after a chemical formula contains a pic "reset" directive. That can be accomplished with an otherwise empty pic diagram. .NH 3 "Data Formats .IP The DFORMAT program \*(r7 produces output suitable for processing by pic \*(r5 to generate data format layouts. For example: .DF I Formatted data format diagram: .begin dformat style fill off style bitwid 0.20 style recspread 0 style recht 0.33333 noname 0-3 \0Version 4-7 IHL 8-15 \0Type of Service 16-31 Total Length noname 0-15 Identification 16-18 \0Flags 19-31 Fragment Offset noname 0-7 Time to Live 8-15 Protocol 16-31 Header Checksum noname 0-31 Source Address noname 0-31 Destination Address noname 0-23 Options 24-31 Padding .end .DE .IP .DF L \0\0\0Source: \&.DS B \&.begin dformat style fill off style bitwid 0.20 style recspread 0 style recht 0.33333 noname 0\-3 \e0Version 4\-7 IHL 8\-15 \e0Type of Service 16\-31 Total Length noname 0\-15 Identification 16\-18 \e0Flags 19\-31 Fragment Offset noname 0\-7 Time to Live 8\-15 Protocol 16\-31 Header Checksum noname 0\-31 Source Address noname 0\-31 Destination Address noname 0\-23 Options 24\-31 Padding \&.end \&.DE .DE .IP Note that dimensions are specified to dformat in inches, and in the example suitable dimensions were chosen to match text format character width (multiples of 0.1 inch) and line height (1/6 inch) so that text and troff\-formatted versions are reasonably consistent. The \e0 sequences are invisible character\-width spaces which improve the text (nroff) output. .NH 3 "Graphs and charts .IP Graphs and charts may be generated from data using the grap preprocessor \*(s0. For example, the following graph: .DS B .G1 # Source: http://www.rfc-editor.org/num_rfc_year.html frame ht 3 wid 4 ; coord x 1965,2005 y 0,300 label left "Number" "of RFCs" left 0.6 ; label bot "YEAR" up 0.066667 label top "Number of RFC documents per YEAR" down 0.233333 ticks left in 0.1 from 0 to 300 by 50 ticks right in 0.1 from 0 to 300 by 50 "" ticks top in 0.1 from 1970 to 2005 by 5 "" ticks bot in 0.05 from 1970 to 2005 by 5 copy thru { line from $1-0.15,0 to $1-0.15,$2 ; \ line from $1-0.15,$2 to $1+0.15,$2 ; \ line from $1+0.15,$2 to $1+0.15,0 } until "EOF" 1968 1 1969 26 1970 57 1971 182 1972 134 1973 161 1974 60 1975 24 1976 12 1977 20 1978 8 1979 7 1980 17 1981 29 1982 37 1983 49 1984 39 1985 41 1986 24 1987 42 1988 46 1989 52 1990 57 1991 95 1992 95 1993 175 1994 185 1995 131 1996 170 1997 192 1998 234 1999 259 2000 279 2001 194 2002 220 2003 235 2004 281 EOF .G2 .DE .IP was produced by the source lines: .DS L \&.DS B \&.G1 # Source: http://www.rfc-editor.org/num_rfc_year.html frame ht 3 wid 4 ; coord x 1965,2005 y 0,300 label left "Number" "of RFCs" left 0.6 ; label bot "YEAR" up 0.066667 label top "Number of RFC documents per YEAR" down 0.233333 ticks left in 0.1 from 0 to 300 by 50 ticks right in 0.1 from 0 to 300 by 50 "" ticks top in 0.1 from 1970 to 2005 by 5 "" ticks bot in 0.05 from 1970 to 2005 by 5 copy thru { line from $1-0.15,0 to $1-0.15,$2 ; \e line from $1-0.15,$2 to $1+0.15,$2 ; \e line from $1+0.15,$2 to $1+0.15,0 } until "EOF" 1968 1 1969 26 1970 57 1971 182 1972 134 1973 161 1974 60 1975 24 1976 12 1977 20 1978 8 1979 7 1980 17 1981 29 1982 37 1983 49 1984 39 1985 41 1986 24 1987 42 1988 46 1989 52 1990 57 1991 95 1992 95 1993 175 1994 185 1995 131 1996 170 1997 192 1998 234 1999 259 2000 279 2001 194 2002 220 2003 235 2004 281 EOF \&.G2 \&.DE .DE .IP Grap produces output in pic input format; it is subsequently processed by pic to generate a graphical representation. There are multiple implementations of both grap and pic, and there is also some interaction between pic\-produced output and formatters. In particular, some implementations of grap produce pic with dimensions unsuitable for generating plain text in Internet\-Draft/RFC format. Authors who include graphs should be aware of these issues; they can be safely ignored if no graphs are included. .IP For consistency, the output produced by grap and pic should be examined to confirm that the height is specified as a multiple of 1/6 inch and the width is a multiple of 0.1 inch, not exceeding 7.2 inches. Placement of labels should also be checked between text (nroff) and PostScript (troff) versions, and adjustments to the source graph specification made as required. .NH 3 "Simple Diagrams .IP Pic \*(r5 can produce simple diagrams. Text output approximation is limited to rectilinear lines, so one should avoid ellipses, splines, etc. Box, line, etc. dimensions should be multiples of character width (0.1 inch) and text line height (1/6 inch) for consistency between text and troff\-formatted documents. For example: .DS L \&.DS B \&.PS boxwid = 0.8 # arrow approximation that looks acceptable in troff and nroff define myarrow X A: [ move right 0.055;\e "<" ljust;line right ($1 \- 0.1);">" rjust;\e move right 0.045 ]\e X User: box ht 0.333333 "User" FS: box ht 0.666667 "File" "System" with .n at User.s \-0, 0.333333 Client: box ht 1.333333 wid 1.1 "Client\e\-" "SMTP" \e with .sw at FS.se +0.5, 0 "SMTP client" rjust at Client.se \-0, 0.166667 move to User.e ; myarrow(0.5) move to FS.e ; myarrow(0.5) move to Client.e ; SMTP: myarrow(1.8) Server: box ht 1.333333 wid 1.1 "Server\e\-" "SMTP" \e with .sw at Here.x, Client.s.y box invis ht 0.5 "SMTP" "Commands/Replies" with .s at SMTP.c box invis ht 0.25 "and Mail" with .n at SMTP.c "SMTP server" ljust at Server.sw -0, 0.166667 move to Server.e.x, FS.e.y ; myarrow(0.5) FS2: box ht 0.666667 "File" "System" \e with .sw at Server.se.x +0.5, FS.s.y \&.PE \&.DE .DE .IP .DS B The diagram looks like this: .PS boxwid = 0.8 # arrow approximation that looks acceptable in troff and nroff define myarrow X A: [ move right 0.055;\ "<" ljust;line right ($1 - 0.1);">" rjust;\ move right 0.045 ]\ X User: box ht 0.333333 "User" FS: box ht 0.666667 "File" "System" with .n at User.s -0, 0.333333 Client: box ht 1.333333 wid 1.1 "Client\-" "SMTP" \ with .sw at FS.se +0.5, 0 "SMTP client" rjust at Client.se -0, 0.166667 move to User.e ; myarrow(0.5) move to FS.e ; myarrow(0.5) move to Client.e ; SMTP: myarrow(1.8) Server: box ht 1.333333 wid 1.1 "Server\-" "SMTP" \ with .sw at Here.x, Client.s.y box invis ht 0.5 "SMTP" "Commands/Replies" with .s at SMTP.c box invis ht 0.25 "and Mail" with .n at SMTP.c "SMTP server" ljust at Server.sw -0, 0.166667 move to Server.e.x, FS.e.y ; myarrow(0.5) FS2: box ht 0.666667 "File" "System" \ with .sw at Server.se.x +0.5, FS.s.y .PE .DE .IP Some versions of pic are able to approximate arrows well; others are not. The example above emulates arrows with a mix of lines and text characters to work around poor approximations of pic arrows. Some implementations of pic generate output for multi\-line text labels which does not work well with some implementations of nroff. Authors who include graphs and diagrams should be aware of these issues; they can be safely ignored if no graphs or diagrams are included. .NH 3 Tables .IP Tables may be formatted using the tbl program \*(r6. Horizontal rules produced in troff\-formatted documents take less vertical space than those formatted by nroff, throwing off page breaks unless special precautions are taken. Consistent vertical space may be forced by using the following sequence of lines to produce full\-width horizontal rules: .DS L \&.mk vP \&.if t .sp 0.33P \&_ \&.if t .sp |\en(vPu+1P .DE .IP Those lines perform the following steps to ensure consistency: .NL .LI Mark the current vertical place in register vP. .LI For troff (but not nroff), move down approximately one\-third of a text line. This approximately centers the horizontal rule in the vertical space in troff. .LI Emit the horizontal rule (see \*(r6 for details); an equals sign instead of an underscore produces a double rule. .LI In troff, move to 1 text line below the previously\-marked vertical position. This corresponds to the vertical position produced by nroff after a horizontal rule. .LE .IP Different implementations of tbl produce slightly different output. For example, horizontal rules in text output are sometimes produced with a series of underscore characters; other implementations may use dash (hyphen) characters. While underscoring looks more attractive in heading rules than hyphens, it can interact poorly with text when used within a table. .IP Some implementations of tbl require extensions specific to a particular implementation of formatters. .NH 3 ABNF .IP ABNF as described in .RR I 2234 \& can be difficult to format. ABNF could be formatted manually as one or more displays, or tbl could be used to align related sets of ABNF rules. Both of those options require significant manual effort. .IP Another option is to use a preprocessor that reads free\-form ABNF and formats it for presentation. A tool is available to parse and format ABNF\-like grammar descriptions (it requires comments not associated with any rule to begin without whitespace before the semicolon (unlike RFC 2234) and does not require an old\-fashioned teletype "carriage return" control character before the end\-of\-line (also unlike RFC 2234)). ABNF is provided between macro lines AS and AE (ABNF start and ABNF end). Within that ABNF section, another macro, BC, is recognized. It causes the current (or subsequent) rule to be formatted with block comments, that is, the comments appear in a block to the right of the rule definition with running comment text formatted in a block approximately the same height as the ABNF definition. .IP For example, the input: .DS L \&.AS 6 72 cgsntr FWS = ( [ *WSP CRLF ] 1*WSP ) / obs-FWS ; Folding white space \&.BC ctext = NO-WS-CTL / ; Non white space controls. %d33-39 / ; The rest of the US-ASCII %d42-91 / ; characters not including "(", %d93-126 ; ")", or "\" ccontent = ctext/quoted-pair/COMMENT comment = "(" *([FWS] ccontent) [FWS] ")" CFWS=*([FwS] comment) (([fws] comment) / fWs) \&.AE .DE .IP produces formatted ABNF which looks like: .AS 6 72 cgsntr FWS = ( [ *WSP CRLF ] 1*WSP ) / obs-FWS ; Folding white space .BC ctext = NO-WS-CTL / ; Non white space controls. %d33-39 / ; The rest of the US-ASCII %d42-91 / ; characters not including "(", %d93-126 ; ")", or "\" ccontent = ctext/quoted-pair/COMMENT comment = "(" *([FWS] ccontent) [FWS] ")" CFWS=*([FwS] comment) (([fws] comment) / fWs) .AE .IP Each rule is placed in a separate display by the ABNF preprocessor so that an ABNF rule won't be split across a page break. Optional arguments to the AS macro are numbers (not troff register references, etc.) which indicate the indent and line length in characters, and one\-character option flags which control processing: .TS H c0 cw(6.4i). Flag Description .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .TH .T& c l. c T{ canonicalize case of character literals; type (letter after '%') is lower\-case, hexadecimal digit letters are upper\-case. Rulename references use the same case as the defining ABNF line. T} d T{ omit display wrappers around output rules, instead separating rules with an empty line. This may be useful if the entire ABNF is placed within a display wrapper. T} g T{ group concatenated elements in parentheses if in an alternation expression T} n T{ normalize repetition specifications: 0*1foo becomes [foo], M[foo bar] becomes *M(foo bar), etc. T} s T{ Combine adjacent quoted strings into a single quoted string where possible T} t T{ topologically sort rules in a ruleset so that productions are defined before use T} r T{ reverse the sense of topological sorting; use precedes definition (ineffective if the t flag is not specified) T} .TE .NH 3 "Client-Server Protocol Exchanges .IP Some documents illustrate client server exchanges such as: .DS I S: 220 foo.example.net C: helo bar.example.com S: 250 blah blah blah C: quit S: 221 Go in peace .DE .IP Depending on the specific protocol and how it is desired to be formatted and grouped, displays, paragraphs, a list, or a table might be used to format such an exchange. The example above uses a single indented display, specified as: .DS L \&.DS I S: 220 foo.example.net C: helo bar.example.com S: 250 blah blah blah C: quit S: 221 Go in peace \&.DE .DE .IP Here is the same example as a variable list: .VL .LI S: 220 foo.example.net .LI C: helo bar.example.com .LI S: 250 blah blah blah .LI C: quit .LI S: 221 Go in peace .LE .IP Lists items are implemented as paragraphs, so formatting as paragraphs will look the same. The list was specified as: .DS L \&.VL \&.LI S: 220 foo.example.net \&.LI C: helo bar.example.com \&.LI S: 250 blah blah blah \&.LI C: quit \&.LI S: 221 Go in peace \&.LE .DE .IP Below is the same example formatted as a table: .TS tab (~); l1 l. S:~220 foo.example.net C:~helo bar.example.com S:~250 blah blah blah C:~quit S:~221 Go in peace .TE .IP The table was specified by: .DS L \&.TS tab (~); l1 l. S:~220 foo.example.net C:~helo bar.example.com S:~250 blah blah blah C:~quit S:~221 Go in peace \&.TE .DE .NH 2 "Postprocessing .IP Scripts are available for use with the awk .IR awk Aho, Alfred V., Weinberger, Peter J., and Kernighan, Brian W., "Awk \(em A Pattern Scanning and Processing Language", 1978, in "UNIX TIME\-SHARING SYSTEM (VOLUME\ 2): UNIX Programmer's Manual", Holt, Rinehart, & Winston, 1979 .IE \& interpreter for postprocessing of text and PostScript formatter output (primarily to reorder pages so that the Table of Contents appears in the correct location, although the postprocessor for text also removes overstriking). A sed .IR sed McMahon, Lee E., "SED \(em A Non\-interactive Text Editor", 1978, "UNIX TIME\-SHARING SYSTEM (VOLUME\ 2): UNIX Programmer's Manual", Holt, Rinehart, & Winston, 1979 .IE \& script is available to assist in preparation of HTML formatting. .NH 2 "Proofreading and Checking Output .IP It is so easy to incorporate references that it is easy to unintentionally include a given reference more than once. While authors can generally be nonchalant about formatting of references, references should be proofread carefully to check for duplicates, references categorized as normative which should instead be informative or vice versa, etc. .IP Henrik Levkowetz' "idnits" program \*(q1 is useful for catching diagrams and tables that exceed the maximum allowed line length. .AP "Macros Specifically for the RFC Editor .IP In addition to the NU, FN, UD, OB, IS, and CA macros discussed in the body of this memo, there are several macros intended for RFC Editor (rather than author) use. They are described in this Appendix. .NH 2 "IESG Notes" u5 .IP The IN macro takes a single numeric argument indicating the type of IESG note to be included; some types take a second argument: .TS H lw(0.4i)2 cw(1.3i)3 cw(4.6i). Type 2nd Argument Text .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .TH .T& c l. 1 none T{ The IESG has not found any conflict between this document and IETF work. T} 2 Working Group T{ The IESG thinks that this work is related to IETF work done in WG Working Group, but this does not prevent publishing. T} 3 Working Group T{ The IESG thinks that publication is harmful to the IETF work done in WG Working Group and recommends not publishing the document at this time. T} 4 Procedure T{ The IESG thinks that this document violates IETF procedures for Procedure and should therefore not be published without IETF review and IESG approval. T} 5 none T{ The IESG thinks that this document extends an IETF protocol in a way that requires IETF review and should therefore not be published without IETF review and IESG approval. T} 6 none T{ The content of this RFC was at one time considered by the IETF, and therefore it may resemble a current IETF work in progress or a published IETF work. This RFC is not a candidate for any level of Internet Standard. The IETF disclaims any knowledge of the fitness of this RFC for any purpose and in particular notes that the decision to publish is not based on IETF review for such things as security, congestion control, or inappropriate interaction with deployed protocols. The RFC Editor has chosen to publish this document at its discretion. Readers of this RFC should exercise caution in evaluating its value for implementation and deployment. See RFC 3932 for more information. T} 7 none T{ This RFC is not a candidate for any level of Internet Standard. The IETF disclaims any knowledge of the fitness of this RFC for any purpose and in particular notes that the decision to publish is not based on IETF review for such things as security, congestion control, or inappropriate interaction with deployed protocols. The RFC Editor has chosen to publish this document at its discretion. Readers of this document should exercise caution in evaluating its value for implementation and deployment. See RFC 3932 for more information. T} 8 none T{ This RFC is not a candidate for any level of Internet Standard. The IETF disclaims any knowledge of the fitness of this RFC for any purpose and notes that the decision to publish is not based on IETF review apart from IESG review for conflict with IETF work. The RFC Editor has chosen to publish this document at its discretion. See RFC 3932 for more information. T} .TE .IP If a type of 0 (zero) is specified, text after the IN macro line is collected. The RFC Editor can use this feature to incorporate an IESG notice other then the ones prescribed in \*(r3 as listed in the table above. .IP The IN macro should be placed in the front matter (before the first SH or NH macro). The corresponding note will be formatted as an unnumbered section appearing before the Abstract. If no IN macro call is placed in the front matter section, no IESG note will be included in the document. .NH 2 "Alternate Document Type and Number" u6 .IP Some RFCs are also BCP, STD, or FYI documents. The RFC Editor may indicate such a document type and number via the AN macro. It takes two arguments; the type (which must be one of BCP, STD, or FYI) and the number corresponding to that type. The information is placed in the first page heading, properly formatted. The AN macro should also be placed in the front matter. .AP "Document Progression Using the rfc Macros .NH 2 "Initial Internet-Draft .IP An initial draft using the rfc macros should specify a draft number version of 00 by supplying a \-1 argument to the NU macro or via command\-line specification of register N. The latter may be accomplished by editing a line in the Makefile. Document category (CA macro) can be ignored, or can be specified to indicate intended status. The draft file name (see \*(r4) should be specified via the FN macro. Long (TL) and short (ST) titles need to be specified, as well as author(s) or editor(s) (AU or ED macro(s)) and Table of Contents parameters (TC macro or command\-line register specifications). An Abstract (AB macro) is required. The remainder of the document is specified by defining sections, paragraphs, lists, and references, plus any diagrams or other non\-textual material. .IP The document is then formatted and the text version submitted as an Internet\-Draft \*(r4. .IP During processing, the rfc macro package checks for certain types of errors and issues warnings and other messages. If such a message appears, it is advisable to consider a revision to the document or other appropriate action. .NH 2 "Subsequent Draft Revisions .IP Each revision involves updating the argument to the NU macro or command\-line register N specification (sequencing to \-2, then \-3, etc.) and making desired changes to the content. Note that if the file name is changed, the numbering must be restarted at 00. If a Makefile is used, it too should be updated to reflect the revised version numbering. .IP The document is reformatted and resubmitted as a revised Draft \*(r4. .NH 2 "Publication as an RFC .IP The Abstract may be retained (possibly edited) or removed. Document category should be specified in consultation with the IETF or RFC Editor. The document number should be left unspecified (0 (zero) argument to the NU macro or command\-line register N specification); the RFC Editor will assign an RFC number at the time of publication. The document is reformatted and sent to the RFC Editor. By prior arrangement with the RFC Editor, the document source can be sent, as that may simplify final formatting by the RFC Editor. .AP "Obtaining the rfc Macros and Related Tools .IP The rfc macros and related tools are currently available at http://users.erols.com/blilly/formatting. Individual files are: .TS H lw(3.2i)2 cw(3.4i). File Description .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .TH .T& l l. tmac.rfc the rfc macros Makefile T{ a makefile used to automate preprocessing, formatting, and postprocessing. It can be modified as needed for specific documents. T} repaginate.awk T{ an awk script used for postprocessing text output. It reorders pages so that the Table of Contents appears in the correct location. T} psrenumber.awk T{ an awk script for postprocessing PostScript output. It reorders pages so that the Table of Contents appears in the correct location. T} htmlize.sed T{ a sed script for HTML markup T} template.rfc T{ Template suitable as a draft starting point T} \*(dr.rfc T{ the source for this document T} \*(dr.txt T{ text output for this document T} \*(dr.ps T{ PostScript output for this document T} \*(dr.pdf T{ PDF output for this document T} \*(dr.psa4 T{ PostScript output for this document, formatted for ISO A4 paper T} \*(dr.pdfa4 T{ PDF output for this document, formatted for ISO A4 paper T} \*(dr.html T{ HTML 4.01 Strict compliant version of this document preserving page layout and numbering T} .TE .IP There are also subdirectories containing source code and related files for the ABNF formatter and reference formatter preprocessors. .if \nN<0 \{ .IP If the macros and related tools are deemed useful, it is hoped that they might be relocated to the RFC Editor site. .\} .NS 10P .AP "Summary of Directives .IP The following table summarizes rfc macro directives in alphabetical order (macros specific to preprocessors and internal use macros are omitted). The section number containing detailed information about each macro is listed. .\" N.B. leave sufficient space for section numbers (tbl runs before troff) .TS H cw(0.4i) cw(0.7i) cw(4.7i). Name Section Description .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .TH .T& c l l. AB \*(t1 Abstract AN \*(u6 Alternate document series number AP \*(u3 Appendix AU \*(s6 Author BL \*(t9 Bullet list CA \*(s3 Category or Intended status DE \*(t6 Display end DF \*(t6 Floating display start DS \*(t6 Display start DT \*(s7 Date ED \*(s6 Editor EM \*(u4 End matter FN \*(s5 (Internet-Draft) file name (w/o version) IB \*(u2 MIB (or MIB\-like) boilerplate IE \*(u1 Informative reference end IN \*(u5 IESG note IP \*(t3 Indented paragraph IR \*(u1 Informative reference start IS \*(s9 Independent submission (to RFC Editor) KE \*(t6 Keep end KF \*(t6 Floating keep start KS \*(t6 Keep start LE \*(t7 List end LI \*(t7 List item LP \*(t3 Left\-aligned paragraph NE \*(u1 Normative reference end NH \*(t2 Numbered section heading NL \*(t8 Numbered list NR \*(u1 Normative reference start NS \*(t5 Needed (vertical) space NU \*(s2 RFC number or draft version OB \*(s4 Obsoleted RFCs ON \*(s0 Optional notice RE \*(t4 Decrease indent RS \*(t4 Increase indent SH \*(t2 (unnumbered) Section heading ST \*(s1 Short title for page heading TC \*(s8 Table of contents specification TL \*(s1 (Long) document title UP \*(s4 Updated RFCs VL \*(t0 Variable list .TE .NS 10P .AP "Source File Directive Order .IP Some directives appear in certain parts of a source document as summarized in the following diagram. For content ordering, see \*(r0. .TS H cw(1.0i) c0w(1.5i) cw(3.2i). Part Directives Comments .mk vP .if t .sp 0.33P = .if t .sp |\n(vPu+1P .TH .T& c c l. T{ Front Matter (before Abstract and first section heading) T} NU RFC or draft version number \^ TL (long) Title \^ ST Short title \^ DT Date override \^ AU Author \^ ED Editor \^ FN Internet\-Draft file name \^ TC Table of contents parameters \^ CA category or Intended status \^ IS Independent submission \^ IN IESG note \^ ON Optional notice \^ AN Alternate series number \^ UP Updated RFCs \^ OB Obsoleted RFCs .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P Abstract AB (required for Internet\-Draft) \^ IP (additional Abstract paragraphs) .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P .sp \0 .\" .sp 5P .\" (continues overleaf) .bp T{ Body and Appendices T} NH Numbered section \^ SH Unnumbered section \^ NS Need (vertical) space \^ \R. \R. \^ IP, LP paragraphs \^ \R. \R. \^ RS, RE Indentation adjustment \^ \R. \R. \^ IR, IE Informative references \^ BR, FR, RR, SR \^ \^ \R. \R. \^ NR, NE Normative references \^ BR, FR, RR, SR \^ \^ \R. \R. \^ DS, DF, DE displays \^ \R. \R. \^ KS, KF, KE keeps \^ \R. \R. \^ BL, NL, VL Lists \^ LI, LE \^ \^ \R. \R. \^ IB MIB (or MIB\-like) copyright notice \^ \R. \R. \^ EQ, EN Mathematical equations \^ \R. \R. \^ TS, TH, T&, TE Tables \^ \R. \R. \^ AS, BC, AE ABNF \^ \R. \R. \^ PS, PE Diagrams \^ \R. \R. \^ G1, G2 Graphs \^ \R. \R. \^ .begin, .end Data formats \^ \R. \R. \^ .cstart, .cend Chemical formulae \^ \R. \R. \^ AP Appendices (after bulk of body) .mk vP .if t .sp 0.33P _ .if t .sp |\n(vPu+1P T{ End Matter T} EM last macro directive in source document .TE .AP "Disclaimers .IP This document has exactly one (1) author. .IP In spite of the fact that the author's given name may also be the surname of other individuals, and the fact that the author's surname may also be a given name for some females, the author is, and has always been, male. .IP The presence of "or she", "/SHE", "each", "their", and "authors" (plural) in the boilerplate sections of this document is irrelevant. The author of this document is not responsible for the boilerplate text. .IP Comments regarding the silliness, lack of accuracy, and lack of precision of the boilerplate text should be directed to the IESG, not to the author. .if \nN<0 \{ .NS 8P .AP "Change History" .IP [[This change history will not be part of a published RFC]] .VL .LI "-04 to -05" .BL .LI provision for specifying list indent for number lists and variable lists; indent for bullet lists computed from bullet string width .LI corrected typo in references .LI [added pdfmark generation for TOC Bookmarks; abandoned effort to provide reference link pdfmark entries] .LI [revised PDF description line generation and made provision for optimization (also cleans up some strange errors)] .LI [added license to macro source file to clarify reusability] .LI removed all\-or\-none restriction w.r.t. document editors .LI added optional third argument to NH to save section number string and optional second argument to AP directive .LI rearranged and reworded data format example .LI [fine\-tuned HTML sed script] .LI updated reference to RFC Editor draft .LI added description of idref preprocessor .LI [revised Makefile to incorporate idref preprocessor] .LI [improvd nested bullet list handling] .LE .LI "-03 to -04" .BL .LI Added information about implementation (preprocessor, formatter, etc.) issues .LI [updated Makefile, macros, scripts to improve compatibility] .LI [updated htmlize.sed to guess at section number references, URIs, and mailboxes] .LI Corrected typos and errors in text .LE .LI "-02 to -03" .BL .LI Added ED macro directive description for document Editor (vs. Author) .LI fixed file list to include draft version suffix .LI added tip regarding duplicate references .LI added mention and reference to idnits .LI [added HTML generation to Makefile] .LI added client\-server exchange examples .LI [revised macros to enforce strict IETF Secretariat boilerplate rules which appear to require authors to be hermaphroditic, transsexual, (individuals) or multi\-gender teams effective 6 May 2005] .LI lowered page count limit for TOC in accordance with ID\-Checklist Revision 1.2 .LI separate paragraphs in RFC 3978 boilerplate (idnits bug fixed) .LI updated reference to March 2005 version of 1id-guidelines (also reported typo, so there'll be yet another version) .LI clarified 0 as zero in default value column of register table in Appendix A .LI added summary of directives .LI added guide to directives in source document sections .LI revised some wording .LI added grap example .LI rearranged directives in front matter to correspond to table in appendix .LI added template document to files .LI [revised Makefile to better handle preprocessors] .LI [revised Makefile to incorporate rfcref preprocessor] .LI added discussion of rfcref preprocessor .LI [revised HTML generation to improve rendition of copyright symbols and bullets] .LI [revised HTML generation to provide reference anchors and links] .LI [revised HTML generation to provide table of contents anchors and links] .LI [split out much of HTML manipulation to htmlize.sed to facilitate maintenance] .LI added additional optional arguments to IB macro directive to accommodate use within MIB syntax .LI added disclaimers of boilerplate silliness, inaccuracy, and imprecision .LE .NS 4P .LI "-01 to -02" .BL .LI added this change history .LI added acknowledgment re. reference style .LI removed extraneous commas from preprocessor reference list .LI corrected typos .LI revised pic for SMTP diagram .LI added section regarding ABNF formatting .LI added caveat regarding multiple paragraphs in a keep .LI added .NS macro to reserve vertical space .LI updated boilerplate for revised BCP\ 78 and BCP\ 79 .LE .NS 4P .LI "-00 to -01" .BL .LI clarified issue w.r.t. low\-level directives (as distinguished from macro call directives) .LI updated Requirement levels to correspond to changed text .LI some extraneous commas unintentionally crept into the list of preprocessor references .LI added description of alternative methods for loading macros .LI updated descriptions to incorporate setting registers from the command line .LI added text regarding draft file name lower-case letters requirement .LI improved usage .LI rearranged some text under Document Content heading .LI added recommendations regarding troff units .LI improved differentiation between keeps and displays .LI improved table formatting .LI added floating keeps and displays .LI added pointer regarding text following a display .LI added optional argument to bulleted list macro .LI added table of single\-character registers .LI added description of formatting for paper sizes other than ANSI\ A .LI added tips and tricks for eqn, chem, dformat, pic, and tbl .LI added description of document progression .LI added ISO A4 versions of formatted documents .LE .LE .\} .\" End matter .EM