ŠĀ Network Working Group B. Lilly Internet Draft January 2005 Updates: 2223 (if approved) Expires: August 1, 2005 Writing Internet-Drafts and Requests For Comments using troff and nroff draft-lilly-using-troff-00 Status of this Memo This document is an Internet-Draft and is subject to all provisions of section 3 of RFC 3667. By submitting this Internet-Draft, the author represents that any applicable patent or other IPR claims of which he is aware have been or will be disclosed, and any of which he become aware will be disclosed, in accordance with RFC 3668. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright Notice Copyright(C)The Internet Society (2005). Abstract 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. Lilly Expires August 1, 2005 [Page 1] Internet Draft Writing I-Ds and RFCs using troff January 2005 Table of Contents 1. Introduction................................................... 3 1.1. Basic Directives Are at Too Low a Level................... 3 1.2. Authors Specify Content Rather Than Issue Directives...... 3 1.3. ms Macros Are Not Designed For RFCs....................... 3 1.4. RFC-specific Macros....................................... 3 2. Requirement Levels............................................. 4 3. Processing..................................................... 4 4. Input Format................................................... 4 5. Specifics...................................................... 5 5.1. Loading the RFC Macros.................................... 5 5.2. Specifying the Document Particulars....................... 5 5.2.1. Titles, Long and Short............................... 5 5.2.2. RFC or Draft Version Number.......................... 6 5.2.3. Document Category (RFCs)............................. 6 5.2.4. Updated and Obsoleted RFCs........................... 6 5.2.5. Internet Draft File Name............................. 6 5.2.6. Authors.............................................. 6 5.2.7. Date................................................. 7 5.2.8. Numbered and Unnumbered Sections and Table of Contents............................................. 7 5.2.9. Independent vs. IETF Submissions..................... 7 5.2.10. Optional Notices.................................... 8 5.3. Document Content.......................................... 8 5.3.1. Abstract............................................. 8 5.3.2. Numbered and Unnumbered Sections..................... 8 5.3.3. Paragraphs........................................... 9 5.3.4. Special Indentation.................................. 9 5.3.5. Keeps and Displays................................... 9 5.3.6. Lists................................................ 10 5.3.7. References........................................... 11 5.3.8. MIB modules, etc..................................... 12 5.3.9. Document Appendices.................................. 13 5.4. End Matter................................................ 13 6. Acknowledgments................................................ 13 7. Security Considerations........................................ 13 8. Internationalization Considerations............................ 13 9. IANA Considerations............................................ 13 Appendix A. Esoterica............................................. 14 A.1. Troff vs. Nroff........................................... 14 A.2. Postprocessing............................................ 14 Appendix B. Macros Specifically for the RFC Editor................ 14 B.1. IESG Notes................................................ 14 B.2. Alternate Document Type and Number........................ 16 Appendix C. Obtaining the rfc Macros and Related Tools............ 16 Normative References.............................................. 16 Informative References............................................ 17 Author's Address.................................................. 18 Lilly Expires August 1, 2005 [Page 2] Internet Draft Writing I-Ds and RFCs using troff January 2005 1. Introduction The Instructions to RFC Authors [N1.RFC2223] describes the editorial format of RFCs and outlines editorial production of Internet Drafts and RFCs using basic troff directives [I1.CSTR54] with the ms macro package [I2.ms] 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. 1.1. Basic Directives Are at Too Low a Level 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 [N1.RFC2223] 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. 1.2. Authors Specify Content Rather Than Issue Directives Another problem with 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". 1.3. ms Macros Are Not Designed For RFCs 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 [N1.RFC2223]. Use of some high-level ms macros results in text which violates some provisions of the [N1.RFC2223] 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 [N1.RFC2223], [I3.RFC1543]. 1.4. RFC-specific Macros 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. Lilly Expires August 1, 2005 [Page 3] Internet Draft Writing I-Ds and RFCs using troff January 2005 2. Requirement Levels The key words "SHOULD" and "SHOULD NOT" in this document are to be interpreted as described in [N2.BCP14]. 3. Processing Production of a document using troff and a macro package proceeds in several stages: 1. A mixture of free-form text, processing directives, and material describing non-textual content (tables, diagrams, etc.) is generated by the author. 2. Preprocessors [I4.CSTR49], [I5.CSTR114], [I6.CSTR116], [I7.CSTR122], [I8.eqn], [I9.CSTR142] may be used to transform descriptions of tables, diagrams, etc. 3. A formatter transforms instructions and other input into a formatted document according to rules corresponding to the desired document format. 4. Some postprocessing may take place to repaginate output and to make final adjustments to the output format. Tools, e.g. [I10.make], are available to automate the preprocessor, formatter, and postprocessing portions of document processing, freeing the author to concentrate on the document content. 4. Input Format 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: Lilly Expires August 1, 2005 [Page 4] Internet Draft Writing I-Ds and RFCs using troff January 2005 .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 is formatted into an indented paragraph which looks like: All bad precedents begin with justifiable measures. A strong conviction that something must be done is the parent of many bad measures. Any excuse will serve a tyrant. The character sequence \" 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 \e, 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. 5. Specifics 5.1. Loading the RFC Macros The first directive should be the line: .so tmac.rfc That directs the processor to read the contents of a file named "tmac.rfc", which contains the macros that describe the RFC format, holds some boilerplate text, and provides convenience functions. 5.2. Specifying the Document Particulars 5.2.1. Titles, Long and Short Each RFC or Internet Draft has a title, one or more authors, etc. These are specified with directives. For example: .TL "Writing Internet\-Drafts and Requests For Comments using troff and\ \& nroff Specifies the document title (TL). The double-quote causes the remainder of the (logical) line to be taken as a single argument to Lilly Expires August 1, 2005 [Page 5] Internet Draft Writing I-Ds and RFCs using troff January 2005 the TL macro; otherwise each space character would be taken as an argument separator. 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. 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 [I1.CSTR54]. There is a short title (ST) macro which is used to specify a short version of the document title for use in the page headings. For this document, that was specified as: .ST "Writing I\-Ds and RFCs using troff 5.2.2. RFC or Draft Version Number RFCs have an RFC number assigned by the RFC Editor, and Internet Drafts have a version number. The number is specified with the NU macro: 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. 5.2.3. Document Category (RFCs) RFCs have a category; one of Experimental, Informational, Standards Track, or Best Current Practice [I11.BCP9]. The category is specified as the argument to the CA macro, which need only be supplied for RFCs (it is ignored in drafts). 5.2.4. Updated and Obsoleted RFCs 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. 5.2.5. Internet Draft File Name 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, which is not necessary (is ignored) for RFCs. 5.2.6. Authors 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: Lilly Expires August 1, 2005 [Page 6] Internet Draft Writing I-Ds and RFCs using troff January 2005 Argument Description --------------------------------------------------------------------- 1 First initial and surname for first page heading 2 First name and/or initials for Author's Address section 3 Surname for page footer and Author's Address section 4 Gender; one of m (male), f (female), or o (other or indeterminate) 5 Internet mailbox 6 Telephone Number 7 Fax Number 8 URL 9 Affiliation The author's gender is used to customize boilerplate verbiage to accommodate enforcers of political correctness. 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 (printed) 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. 5.2.7. Date 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 arguments (4-digit year, month, and day respectively). 5.2.8. Numbered and Unnumbered Sections and Table of Contents An RFC or Internet Draft may contain numbered sections. Sections may have subsections, and the section level represents the level of subsections. This section of this document has level 3. 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. 5.2.9. Independent vs. IETF Submissions Internet Drafts and RFCs may be products of IETF Working Groups or other IETF entities, or they may be independent submissions. The macro IS is used to identify independent submissions, as there is a slight difference in the boilerplate text which accompanies them. The IS macro takes no arguments. Unfortunately, the IETF Secretariat rejects independent submissions that have the independent submission boilerplate required by the RFC Editor [I12.Instruct] (bottom of page 33), probably because it is not recognized by Henrik Levkowetz' "idnits" program. Therefore, until Lilly Expires August 1, 2005 [Page 7] Internet Draft Writing I-Ds and RFCs using troff January 2005 the IETF Secretariat and the RFC Editor resolve their differences the IS macro SHOULD NOT be used except by the RFC Editor. 5.2.10. Optional Notices Certain optional notices may be placed at the front of Internet Drafts. The ON macro can be used to specify one of the following notices via a numerical argument: Type Text --------------------------------------------------------------------- 1 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. 2 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. 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: .ON 1 1.2.3 produces the text: 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. 5.3. Document Content 5.3.1. Abstract Having specified such preliminary information, the document content may be specified. 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. 5.3.2. Numbered and Unnumbered Sections 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 takes two arguments: the section level and the section heading text. Numbering for numbered sections is computed automatically. Lilly Expires August 1, 2005 [Page 8] Internet Draft Writing I-Ds and RFCs using troff January 2005 5.3.3. Paragraphs 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). Unindented paragraphs are possible via the LP macro. 5.3.4. Special Indentation Indentation may be controlled with RS and RE macros. The RS macro will increase the indent level by the indentation increment of 3 character spaces, while the RE macro will reduce indentation by that amount. 5.3.5. Keeps and Displays 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. In some cases, ordering of the output is flexible; a "floating" keep may be used (the output of the keep may appear after some text which follows the keep). In that case, use the KF macro instead of KS to start the keep. More complex groupings can be obtained by "displays". Displays are started like keeps, using the DS macro (there are no floating displays, but a display may be placed in a floating keep). 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: Display Type Description --------------------------------------------------------------------- C Each line of text is centered B The input lines are read as a block, and the block is centered L The display is left-aligned I The display is indented by the amount indicated by an optional second argument (default is 3 character spaces) 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: Lilly Expires August 1, 2005 [Page 9] Internet Draft Writing I-Ds and RFCs using troff January 2005 .DS C War is Peace Freedom is Slavery Ignorance is Strength .\" Eric Arthur Blair, a.k.a. George Orwell .DE produces output in which each line is centered: War is Peace Freedom is Slavery Ignorance is Strength whereas the input: .DS B War can still settle problems, but it can only settle them the wrong way. \" Bertrand Russell .DE produces the text lines as a centered block: War can still settle problems, but it can only settle them the wrong way. 5.3.6. Lists 5.3.6.1. Numbered Lists The NL macro initializes a numbered list. It takes three optional arguments: 1. a prefix string. The default is an empty string (no prefix). 2. a one-character numbering format; one of 1 number using Arabic numerals (the default) I number using Roman numbers expressed as upper-case letters i number using Roman numbers expressed as lower-case letters A letter with upper-case letters a letter with lower-case letters 3. a suffix string. The default is a period. 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. The most recently started list is terminated with the LE (list end) macro. Lilly Expires August 1, 2005 [Page 10] Internet Draft Writing I-Ds and RFCs using troff January 2005 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. 5.3.6.2. Bulleted Lists A bulleted list is initialized with the BL macro, which takes no arguments. List items also use the LI macro and the LE macro ends a bulleted list. The input lines: .BL .LI first bulleted item .LI second bulleted item .LE produce the output: o first bulleted item o second bulleted item 5.3.6.3. Variable Lists The VL macro initializes a variable list. Each list item is labeled with a string supplied as an argument to that item's LI macro. The LE macro terminates a variable list. 5.3.7. References 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: [N1.RFC2223]. 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 user-supplied 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 was specified by the lines: Lilly Expires August 1, 2005 [Page 11] Internet Draft Writing I-Ds and RFCs using troff January 2005 .NR RFC2223 r1 Postel, J. and J. Reynolds, "Instructions to RFC Authors", RFC\ 2223, October 1997. .NE 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. The bracketed reference appears in the text at the place where the NR/NE or IR/IE macros are placed, while the actual reference 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 is 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 \& 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. 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 \*(r1. 5.3.8. MIB modules, etc. 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 [N3.BCP78]. 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 [N3.BCP78], and the optional second argument permits specifying something other than "MIB module". The types are: Type Text --------------------------------------------------------------------- 1 Copyright(C)The Internet Society 2005. This version of this MIB module is part of RFC XXXX; see the RFC itself for full legal notices. Lilly Expires August 1, 2005 [Page 12] Internet Draft Writing I-Ds and RFCs using troff January 2005 Type Text --------------------------------------------------------------------- 2 Copyright(C)The 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. 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". 5.3.9. Document Appendices 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 takes a single argument, the appendix heading text. Subdivided sections within an appendix can be introduced with second-, third-level, etc. numbering via NH macros as with document body sections. 5.4. End Matter At the very end of the input file describing the document, the author should place an EM macro. 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 30 pages in length, a Table of Contents is also produced. 6. Acknowledgments The author gratefully acknowledges the discussions of RFC formatting on the rfc-interest mailing list. 7. Security Considerations No security considerations are addressed by this memo. 8. Internationalization Considerations This memo raises no new internationalization considerations. 9. IANA Considerations This memo adds no new IANA considerations. Lilly Expires August 1, 2005 [Page 13] Internet Draft Writing I-Ds and RFCs using troff January 2005 Appendix A. Esoterica A.1. Troff vs. Nroff 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.0 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 [N1.RFC2223] is not necessary); output processed by troff does not. A.2. Postprocessing Scripts are available for use with the awk [I13.awk] 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). Appendix B. Macros Specifically for the RFC Editor 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. B.1. IESG Notes The IN macro takes a single numeric argument indicating the type of IESG note to be included; some types take a second argument: Type 2nd Argument Text --------------------------------------------------------------------- 1 none The IESG has not found any conflict between this document and IETF work. 2 Working Group The IESG thinks that this work is related to IETF work done in WG Working Group, but this does not prevent publishing. 3 Working Group 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. Lilly Expires August 1, 2005 [Page 14] Internet Draft Writing I-Ds and RFCs using troff January 2005 Type 2nd Argument Text --------------------------------------------------------------------- 4 Procedure The IESG thinks that this document violates IETF procedures for Procedure and should therefore not be published without IETF review and IESG approval. 5 none 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. 6 none 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. 7 none 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. 8 none 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. 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 [N3.BCP78] as listed in the table above. Lilly Expires August 1, 2005 [Page 15] Internet Draft Writing I-Ds and RFCs using troff January 2005 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. B.2. Alternate Document Type and Number 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. Appendix C. Obtaining the rfc Macros and Related Tools The rfc macros and related tools are currently available at http://users.erols.com/blilly/formatting. Individual files are: File Description --------------------------------------------------------------------- tmac.rfc the rfc macros makefile a makefile used to automate preprocessing, formatting, and postprocessing. It can be modified as needed for specific documents. repaginate.awk an awk script used for postprocessing text output. It reorders pages so that the Table of Contents appears in the correct location. psrenumber.awk an awk script for postprocessing PostScript output. It reorders pages so that the Table of Contents appears in the correct location. draft-lilly-using-troff-00.tbl the source for this document draft-lilly-using-troff-00.ntbl Same as above, but with a different name due to preprocessing procedural details draft-lilly-using-troff-00.txt text output for this document draft-lilly-using-troff-00.ps PostScript output for this document draft-lilly-using-troff-00.pdf PDF output for this document If the macros and related tools are deemed useful, it is hoped that they might be relocated to the RFC Editor site. Normative References [N1.RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", RFC 2223, October 1997. Lilly Expires August 1, 2005 [Page 16] Internet Draft Writing I-Ds and RFCs using troff January 2005 [N2.BCP14] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [N3.BCP78] Bradner, S., "IETF Rights in Contributions", BCP 78, RFC 3667, February 2004. Informative References [I1.CSTR54] Ossanna, Joseph F., "NROFF/TROFF User's Manual", Computing Science Technical Report No.54, Bell Laboratories, Murray Hill, New Jersey, 1976. [I2.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 [I3.RFC1543] Postel, J., "Instructions to RFC Authors", RFC 1543, October 1993. [I4.CSTR49] Lesk, M. E., "TBL - A Program for Setting Tables", Bell Laboratories Computing Science Technical Report #49, Murray Hill, New Jersey, 1976. [I5.CSTR114] 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. [I6.CSTR116] 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. [I7.CSTR122] 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. [I8.eqn] Kernighan, Brian W, and Cherry, Lorinda L., "A System for Typesetting Mathematics", Communications of the ACM 18, 182-193, 1975. [I9.CSTR142] 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. [I10.make] Feldman, S. I., "Make --A Program for Maintaining Computer Programs", 1978, in "UNIX TIME-SHARING SYSTEM (VOLUME 2) : UNIX Programmer's Manual", Holt, Rinehart, & Winston, 1979 Lilly Expires August 1, 2005 [Page 17] Internet Draft Writing I-Ds and RFCs using troff January 2005 [I11.BCP9] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. [I12.Instruct] Reynolds, J., and R. Braden, "Instructions to Request for Comments (RFC) Authors", Work in progress (August 2004). [I13.awk] Aho, Alfred V., Wienberger, Peter J., and Kernighan, Brian W., "Awk --A Pattern Scanning and Processing Language", 1978, in "UNIX TIME-SHARING SYSTEM (VOLUME 2): UNIX Programmer's Manual", Holt, Rinehart, & Winston, 1979 Author's Address Bruce Lilly Email: blilly@erols.com Full Copyright Statement Copyright(C)The Internet Society (2005). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the author retains all his rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary Lilly Expires August 1, 2005 [Page 18] Internet Draft Writing I-Ds and RFCs using troff January 2005 rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Lilly Expires August 1, 2005 [Page 19]