idnits 2.17.00 (12 Aug 2021) /tmp/idnits9508/draft-shirey-ugli-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2022-05-20) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 408 has weird spacing: '...] Last non-b...' == Line 414 has weird spacing: '...] Last non-b...' == Line 1055 has weird spacing: '...t nroff does...' == Line 1056 has weird spacing: '... spaces like ...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (29 December 1999) is 8178 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'Hain' is defined on line 1670, but no explicit reference was found in the text == Unused Reference: 'R1208' is defined on line 1680, but no explicit reference was found in the text == Unused Reference: 'R1983' is defined on line 1683, but no explicit reference was found in the text == Unused Reference: 'Shir' is defined on line 1695, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ANSI' == Outdated reference: draft-hain-msword-template has been published as RFC 3285 ** Downref: Normative reference to an Informational draft: draft-hain-msword-template (ref. 'Hain') -- Possible downref: Non-RFC (?) normative reference: ref. 'Ossa' ** Downref: Normative reference to an Informational RFC: RFC 1208 ** Downref: Normative reference to an Informational RFC: RFC 1983 -- Possible downref: Non-RFC (?) normative reference: ref. 'R2223' -- Possible downref: Non-RFC (?) normative reference: ref. 'Shir' Summary: 6 errors (**), 0 flaws (~~), 11 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Engineering Task Force R. Shirey 2 INTERNET-DRAFT GTE / BBN Technologies 3 Expiration Date: 29 June 2000 29 December 1999 5 The UGLI Method: 6 Using Gargantuanware to Layout Internet Documents 7 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of section 10 of RFC 2026 *except* that the right to 13 produce derivative works is *not* granted. (See copyright notice.) 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 Copyright Notice 33 Copyright (C) GTE / BBN Technologies (1999). All Rights Reserved. 34 (If and when this document becomes an Informational RFC, it will 35 carry the standard Internet Society copyright.) 37 Abstract 39 The ASCII-text file format of Request for Comments (RFC) documents 40 was devised decades ago when the authoring tools were line editors 41 like vi and text processors like nroff. The format still has great 42 utility because it meets the constraints of many kinds of printing 43 and display equipment, but it is difficult to produce with some of 44 today's desktop publishing tools. This paper describes the RFC text 45 file format and discusses its fine points; this should be useful to 46 authors of RFCs and Internet Drafts regardless of their tools. This 47 paper also describes the UGLI method, a hybrid method for producing 48 RFCs by using modern software for composition and editing and using 49 older software, applied in "cookbook" fashion, to finish the job. The 50 method is described in terms of Microsoft Word on an Apple Macintosh 51 but is easily adaptable for other word processors on other platforms. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 56 1.1 The Problem . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.2 An UGLI Solution . . . . . . . . . . . . . . . . . . . . 6 58 1.3 Five UGLI Phases . . . . . . . . . . . . . . . . . . . . 6 59 2. Format Requirements for RFCs . . . . . . . . . . . . . . . . 8 60 2.1 Explicit Requirements for Characters, Lines, and Pages . 8 61 2.1.1 Placement of Form Feed Characters . . . . . . . . . 9 62 2.1.2 Number of Lines per Page . . . . . . . . . . . . . 10 63 2.1.3 ASCII Characters . . . . . . . . . . . . . . . . . 11 64 2.1.4 Blank Lines . . . . . . . . . . . . . . . . . . . . 12 65 2.1.5 Right Page Margin . . . . . . . . . . . . . . . . . 13 66 2.2 Explicit Requirements for Page Headers and Footers . . . 13 67 2.3 Implicit Requirements for Numbering and Indenting . . . . 15 68 2.4 Other Requirements . . . . . . . . . . . . . . . . . . . 16 69 2.4.1 Bullet Paragraphs . . . . . . . . . . . . . . . . . 16 70 2.4.2 Content Tables . . . . . . . . . . . . . . . . . . 16 71 2.4.3 Exhibits . . . . . . . . . . . . . . . . . . . . . 17 72 2.4.4 Terminology . . . . . . . . . . . . . . . . . . . . 17 73 3. The Word View . . . . . . . . . . . . . . . . . . . . . . . . 19 74 4. The nroff View . . . . . . . . . . . . . . . . . . . . . . . 20 75 4.1 Basic Formatting . . . . . . . . . . . . . . . . . . . . 20 76 4.1.1 Page Length . . . . . . . . . . . . . . . . . . . . 20 77 4.1.2 Line Length . . . . . . . . . . . . . . . . . . . . 20 78 4.1.3 Hyphenation and Adjustment . . . . . . . . . . . . . 21 79 4.2 Text Filling and First Page Header . . . . . . . . . . . 21 80 4.3 Page Breaks . . . . . . . . . . . . . . . . . . . . . . . 23 81 4.3.1 Macro Definition . . . . . . . . . . . . . . . . . 23 82 4.3.2 Setting a Trap to Invoke the Macro . . . . . . . . 24 83 4.4 Indenting, Centering, and Pagination . . . . . . . . . . 25 84 4.5 Pagination Enhancements . . . . . . . . . . . . . . . . . 26 85 5. The Five Phases Step-by-Step . . . . . . . . . . . . . . . . 29 86 5.1 Draft Document in Word . . . . . . . . . . . . . . . . . 29 87 5.2 Prepare File for nroff Processing . . . . . . . . . . . . 29 88 5.2.1 Create a Dual-View File . . . . . . . . . . . . . . 30 89 5.2.2 Properly Save As a Text File . . . . . . . . . . . 30 90 5.3 Process File in nroff . . . . . . . . . . . . . . . . . . 31 91 5.3.1 Move nroff Input to UNIX System . . . . . . . . . . 31 92 5.3.2 Run nroff Command . . . . . . . . . . . . . . . . . 32 93 5.3.3 Get nroff Output from UNIX System . . . . . . . . . 32 94 5.4 Do Final Editing and Prepare for vi . . . . . . . . . . . 32 95 5.5 Process File in vi . . . . . . . . . . . . . . . . . . . 34 96 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 97 7. Security Considerations . . . . . . . . . . . . . . . . . . . 35 98 8. Author's Address . . . . . . . . . . . . . . . . . . . . . . 35 99 9. Expiration Date . . . . . . . . . . . . . . . . . . . . . . . 35 101 Table of Figures 103 1. UGLI Phases . . . . . . . . . . . . . . . . . . . . . . . . . 7 104 2. Result of Failure to Turn Off Filling . . . . . . . . . . . . 22 105 3. Sample of "ASCII Art" . . . . . . . . . . . . . . . . . . . . 23 106 4. Examples of Centering and Indenting . . . . . . . . . . . . . 25 107 5. Examples of Keeping Lines Together . . . . . . . . . . . . . 27 108 6. UGLI Phases and Files . . . . . . . . . . . . . . . . . . . . 29 109 7. "Find" and "Replace" Strings . . . . . . . . . . . . . . . . 33 111 Table of Fragments 113 1. Specifying Basic Formatting . . . . . . . . . . . . . . . . . 20 114 2. Specifying First Page Header . . . . . . . . . . . . . . . . 21 115 3. Specifying Footer, Page Break, and Running Header . . . . . . 23 116 4. Last Line of nroff Input File . . . . . . . . . . . . . . . . 25 117 5. Page Boundary in nroff Output File . . . . . . . . . . . . . 32 118 6. Page Boundary in RFC Format . . . . . . . . . . . . . . . . . 33 119 7. Page Boundary in vi Input File . . . . . . . . . . . . . . . 33 121 Table of Tables 123 1. ASCII Control Characters . . . . . . . . . . . . . . . . . . 11 124 2. ASCII Graphic Characters . . . . . . . . . . . . . . . . . . 12 126 1. Introduction 128 The Request for Comments (RFC) document series is the official 129 publication channel for Internet Standards and other Internet 130 community information [R2026]. RFC 2223 [R2223] tells how to format 131 and submit an RFC. Every RFC must be available in ASCII text. Some 132 RFCs are also available in a secondary format, PostScript, but the 133 ASCII version is the definitive reference. 135 The RFC series began in 1969, and its easy-to-read, time-tested file 136 format was codified soon after. At that time, the Internet community 137 produced documents mainly by using line editors (e.g., vi) to create 138 input files for nroff [Ossa] and similar programs that format text 139 for typesetter- and typewriter-like terminals. Today, people use 140 sophisticated word processing software, such as Microsoft Word, Corel 141 WordPerfect, Lotus Word Pro, and Adobe PageMaker. Surprisingly, 142 although RFC format was fairly easy to produce with the older tools, 143 it often is difficult or impossible to produce with newer desktop 144 publishing systems. 146 This paper describes a method for producing RFC format using a hybrid 147 of old and new tools. It is called Using Gargantuanware to Layout 148 Internet Documents (UGLI), where "gargantuanware" refers to the 149 large, elaborate desktop publishing tools such as Word that are 150 overkill for producing the RFC format. As suggested by the acronym 151 "UGLI", the method is not pretty, but it does the job well. UGLI is 152 described here for Microsoft Word on a Macintosh, but the method is 153 easily adaptable for other word processors and platforms. It uses a 154 modern word processing tool for the composition and editing work and 155 then uses older tools, nroff and vi, for the final steps. This paper 156 assumes that you know how to use Word or some equivalent tool. 157 However, you do not need to know nroff or vi; complete step-by-step 158 instructions are provided here for using them. 160 1.1 The Problem 162 As RFC 2223 says, "Online RFC files are copied by interested 163 people and printed or displayed at their site on their equipment. 164 This means that the format of the online files must meet the 165 constraints of a wide variety of printing and display equipment." 166 Thus, the primary format for RFCs remains ASCII text. Also, for 167 comprehensibility, esthetics, readability, and tradition, "The RFC 168 Editor attempts to ensure a consistent RFC style"; and that style 169 involves typography that originated with nroff. 171 The RFC format is also used for other Internet Standards Process 172 [R2026] documents (ISPDs). Prior to publication of an RFC, the 173 material is made available to the Internet community as an 174 Internet-Draft (I-D), which also is formatted as an ASCII text 175 file. Most I-Ds appear in RFC format because their authors usually 176 intend them to become RFCs. However, greater freedom is permitted 177 in formatting I-Ds than RFCs. Consequently, many I-D authors avoid 178 full compliance with RFC 2223, apparently because the RFC 179 requirements are difficult to satisfy. 181 Section 2 of this paper describes in detail the format for ASCII 182 text RFCs. Both the requirement for ASCII text and the specified 183 typography cause trouble for Word. Despite the simplicity of the 184 RFC format, some features are impossible to achieve in an ASCII 185 text file by using only Word. At its heart, Word assumes that a 186 document file will be displayed on the computer's screen for 187 WYSIWYG editing and then will be printed on paper. Word maintains 188 a specially formatted file for displaying the document, but that 189 formatting is lost if the document is saved as a text file. 191 For example, RFC sections and subsections must be decimal numbered 192 in outline style as "1.", "1.1", "1.1.1", and so on. Headings and 193 paragraphs are stairstep indented by three spaces for each level, 194 as illustrated by this I-D. Word has "style" features for 195 automatically numbering and indenting for display or printing, but 196 that formatting is lost if the author does a "Save As" to create a 197 "Text Only" or "Text Only with Line Breaks" file. 199 For some lost formatting, there are easy workarounds. For example, 200 the author can number sections manually. Revisions may force 201 renumbering, but that is not too laborious except in very large, 202 complex documents. Also, renumbering really needs to be done only 203 once, in the final draft. 205 For some other lost formatting, such as stairstep indenting, 206 available workarounds are not practical. For example, in the text 207 file for this I-D, each line of this paragraph must begin with six 208 blank characters, but Word does not put in leading blanks when 209 saving indented material to a text file. The author can put in 210 leading blanks before saving the file as text, but then the author 211 loses many advantages of using Word for editing, such as being 212 able to globally substitute one word or phrase for another. 213 Substituting in a line typically changes where the ends of many of 214 the following lines occur in the same paragraph, and where the 215 ends of pages occur. This forces the author to manually remove and 216 reinsert the sets of leading blanks and the page headers and 217 footers, which is prohibitively time-consuming and error-prone. 219 For still other lost formatting, there is no workaround in Word. 220 For example, each RFC page must be limited to 58 lines plus a form 221 feed (FF, ASCII decimal 12) on a line by itself. Word has features 222 to automatically paginate for display or printing, or the author 223 can instead manually insert "Page Break" symbols. However, all 224 pagination markers, both automatic (soft) and manual (hard), are 225 lost when the author uses "Save As" to create a text file. 227 Mike Gahrns and Tony Hain of Microsoft Corporation specified a 228 method for using Word 97 to produce a file that satisfies RFC 229 2223, but their method does not apply widely. First, it is 230 specific to Word 97, although Gahrns and Hain say it should be 231 possible to "create a similar template for other versions" of 232 Word. Second, the method depends on output from a generic text 233 printer driver. Such a driver is not available with Macintosh Word 234 and may not be in other environments. Third, the method requires 235 an additional Win16/32 executable program to correct the output 236 from the printer driver so that each line and each page terminates 237 with the control characters required by RFC 2223. In short, their 238 method is not easily portable across the wide range of desktop 239 publishing environments found in the Internet community. 241 1.2 An UGLI Solution 243 RFC 2223 says, "RFCs in ASCII Format may be submitted to the RFC 244 Editor ... in either the finished publication format or in nroff", 245 and, "The RFC Editor may choose to reformat the RFC submitted." 247 When you take pride in your work, you prefer that no one reformats 248 that work or otherwise changes the final version. Therefore, you 249 submit your RFC in the finished publication format. If you do not, 250 it is probably because you don't know how to achieve that form. 251 UGLI solves that problem for you. 253 UGLI is applicable, or at least adaptable, to a wide range of 254 desktop publishing environments. In UGLI, you first use Word or a 255 comparable word processor for things that modern word processors 256 do well, such as outlining, typing with automatic correction, 257 cutting and pasting, searching and replacing, and checking 258 spelling and grammar. Next, you enhance the Word file and create a 259 text file for input to nroff. This paper assumes that you know how 260 to use your word processor, but does not assume that you know 261 nroff. Step-by-step, "cookbook" instructions are provided here for 262 creating RFC format with nroff. After running nroff, you again use 263 Word for some polishing, and then briefly use vi or a comparable 264 text editor to insert control characters needed in the final file 265 format of an RFC. You only need to type three vi commands, for 266 which complete instructions are provided here. 268 Authors that use a Macintosh or Windows operating system normally 269 do not have nroff or vi on their platforms. However, they usually 270 can access a UNIX host, and nearly every UNIX host has nroff and 271 vi available. The UNIX host that this author uses for UGLI is his 272 departmental POP3 host, the one from which Eudora retrieves his 273 mail. The user identifier and password that Eudora uses to 274 retrieve mail provides the account for running nroff and vi. 276 1.3 Five UGLI Phases 278 UGLI has five phases, as shown in Figure 1. This section briefly 279 describe the phases; later sections discuss them in detail. 281 ------------------------------------------------------------------ 282 Figure 1. UGLI Phases 284 +----------+ +-----------+ +----------+ +-----------+ +----------+ 285 | 1. Draft | | 2. Add | | 3. Run | | 4. Polish | | 5. Run | 286 | RFC In | | nroff Ops | | nroff on | | RFC In | | vi on | 287 | MS Word | | To File | | Text File| | MS Word | | Text File| 288 +----------+ +-----------+ +----------+ +-----------+ +----------+ 290 ------------------------------------------------------------------ 292 In Phase 1, you compose your RFC in Word. Section 2 describes the 293 RFC format, and Section 3 provides guidance for configuring a Word 294 file to resemble a finished RFC, so that you can see approximately 295 what your final product will look even while you are still working 296 in Word. However, if you save that Word file as a text file, the 297 RFC formatting done by special Word features will be lost. 299 In Phase 2, therefore, you enhance the Word file by inserting 300 nroff commands (called "requests") that will create the RFC format 301 after you save the file as a text file. Section 4 provides 302 "cookbook" directions and examples for nroff. The Word formatting 303 established in Phase 1 provides a visual guide for inserting the 304 correct requests. Also, the requests called for by Section 4 are 305 simplified so that debugging work should be minor or non-existent. 307 You should format nroff requests as "hidden text" in Word, so that 308 you can hide them when you want to print or view a rough draft of 309 the RFC directly from Word without going through nroff. You can 310 create this "dual use/dual view" Word/nroff file by performing 311 Phases 1 and 2 serially; or you can do them in parallel, putting 312 in nroff requests at that same time that you compose and edit the 313 RFC text. Then, you save the Word file, including the embedded 314 nroff requests, as a text file, which becomes nroff's input file. 316 In Phase 3, you move that file to a UNIX host, and you run nroff 317 on that file. You only need to type one simple nroff command. 319 In Phase 4, you move nroff's output back to Word and review the 320 result. If changes are needed, you return to Phase 1 or 2. If not, 321 you do cleanup editing in Word, including putting page numbers 322 into the RFC's table of contents and getting ready to process the 323 file with vi. You then save the Word file as a text file, which 324 becomes vi's input file for the next phase. 326 In Phase 5, you move the file to a host that has vi or a similar 327 line editor program. You use vi to put a form feed character on 328 the last line of each page. You only need to type three simple vi 329 commands. You then move vi's output file, which now completely 330 satisfies the requirements of RFC 2223, back to where you have 331 Word, so that you can easily review and print the file. 333 2. Format Requirements for RFCs 335 This section is *not* the official specification of RFC format; for 336 that, see section 3 RFC 2223. But this is a more complete 337 specification. First, this section points out some less-than-obvious 338 implications and nuances of requirements that RFC 2223 states 339 explicitly. Second, this section explicitly states requirements that 340 RFC 2223 only implies. Third, this section addresses some topics that 341 RFC 2223 ignores completely. The key words "MAY", "MUST", "MUST NOT", 342 and "SHOULD" are intended to be interpreted the same way as in an 343 Internet Standard [R2119], but they represent only this author's 344 interpretations of RFC 2223. 346 o RFC 2223 states explicit requirements for characters, lines, and 347 pages. Here, Section 2.1 explains those rules and suggests 348 revisions and extensions to improve RFC appearance and efficiency. 350 o RFC 2223 states explicit requirements for page headers and 351 footers. Section 2.2 explains those rules. 353 o RFC 2223 says, "Please do look at some recent RFCs and prepare 354 yours in the same style." That implies requirements for section 355 numbering and indenting. Section 2.3 states those rules. 357 o RFC 2223 neither specifies nor implies formatting for many other 358 aspects of an RFC, such as how to handle "bullets" and exhibits 359 (figures, tables, and so on). Section 2.4 makes suggestions for 360 those things, and this I-D provides examples for them and for all 361 the other format features mentioned in this section. 363 2.1 Explicit Requirements for Characters, Lines, and Pages 365 Section 3a of RFC 2223 states text format requirements, which this 366 section reorders and numbers as eight "rules". (RFC 2223 also bans 367 footnotes and recommends that cross-references point to section 368 numbers instead of page numbers, but those constraints do not 369 affect UGLI and are not discussed further in this I-D.) 371 o Rule 1: "The character codes are ASCII [ANSI]." 373 o Rule 2 (Width): "Each line must be limited to 72 characters 374 followed by carriage return [CR, ASCII decimal 13] and line 375 feed [LF, ASCII decimal 10]." This could be restated as 376 follows: each line MUST contain at least 2 and at most 74 377 characters, and the last two on each line MUST be CR and LF. 379 o Rule 3 (Height) : "Each page must be limited to 58 lines 380 followed by a form feed [FF, ASCII decimal 12] on a[n 381 additional] line by itself." 383 o Rule 4: "[The foregoing] 'height' and 'width' [rules] include 384 any headers, footers, page numbers, or left side indenting." 386 o Rule 5: "No overstriking (or underlining) is allowed." 388 o Rule 6: "Use single spaced text within a paragraph, and one 389 blank line between paragraphs." 391 o Rule 7: "Do not fill the text with extra spaces to provide a 392 straight right margin." 394 o Rule 8: "Do not do hyphenation of words at the right margin." 396 The following interpretation and analysis of these rules reveals 397 problems that lead to suggestions for revising some of them. 399 2.1.1 Placement of Form Feed Characters 401 The first four rules are not entirely simple to satisfy. First, 402 notice that Rule 3 applies to *every* page, including the last 403 page. Next, looking at Rule 3 alone, you might think that it 404 has two equally correct interpretations: 406 o Interpretation 1 for Rule 3: 408 [Line m of page n ] Last non-blank line of page. CR LF 409 [Line m+1 of page n ] FF 410 [Line 1 of page n+1] First non-blank line of page. CR LF 412 o Interpretation 2 for Rule 3: 414 [Line m of page n ] Last non-blank line of page. CR LF 415 [Line m+1 of page n ] FF CR LF 416 [Line 1 of page n+1] First non-blank line of page. CR LF 418 The combination of Rules 2 and 3 implies that interpretation 1 419 is incorrect; you don't get another "line" unless you have a 420 line feed. Interpretation 2 is correct; a line containing the 421 FF character (the last line of a page) must be terminated by CR 422 and LF characters, just like all other lines on a page. 424 Interpretation 2 has somewhat unexpected consequences when you 425 view an RFC. When a file satisfies Rule 3 and you display or 426 print that file with Word, you might suppose that you get 58- 427 line pages separated by Word "page breaks". Instead, assuming 428 that each page has the maximum number of lines permitted by 429 Rule 3, you get the following: 431 o Page 1 prints only 58 lines, from the first, non-blank line 432 of the header to the last, non-blank line of the footer. 433 That is because the first character on the 59th line of the 434 file (i.e., the 59th line of page 1, as viewed by Rule 3) is 435 an FF. So right after the 58th line, the printer begins a 436 new page, page 2. 438 o Next, more surprisingly, the 59th line of the file also 439 causes a blank line to print at the top of page 2. That is 440 because immediately after the FF there is a CR that prints 441 nothing visible and an LF that shifts printing to the next 442 line, the second line of the page, where the first, non- 443 blank header line of page 2 is printed. 445 o Similarly, a blank line is printed at the top of every page 446 after page 1, and a final blank page (consisting of one 447 blank line and nothing else) is printed after the final 448 numbered page of the RFC. 450 To summarize, when you display an RFC that conforms with Rules 451 2 and 3, page 1 is seen to have 58 (or fewer) lines (counting 452 from the first, non-blank line of the header to the last, non- 453 blank line of the footer). All other numbered pages have one 454 more line than page 1; they start with a blank line and 455 continue with 58 (or fewer) more lines like on page 1. Thus, 456 when you print, you get the ugly result that page 1 starts one 457 line closer to the top edge of the paper, and ends one line 458 farther away from the bottom edge, than do the other pages. 460 The difference between page 1 and the other pages is hardly 461 noticeable if you read the text on a screen or print only one 462 copy with one RFC page per page of paper. But the difference 463 becomes noticeable if you print camera copy for a multi-copy 464 distribution or print two RFC pages per paper page in order to 465 save space, weight, or trees. (Have you noticed the difference 466 before? It should occur regardless of whether Word or another 467 tool is used for printing.) 469 UGLI's output should not be "ugly". Therefore, Phase 4 includes 470 a step to "correct" your RFC by adding a blank line at the 471 beginning, so that page 1 will display just like all the other 472 pages do. This I-D has been repaired in that way. (Of course, 473 it would be better if the RFC Editor would change the rules to 474 effect interpretation 1 for Rule 3.) 476 2.1.2 Number of Lines per Page 478 The combination of Rules 3 and 4 leaves a loophole that can 479 result in truly ugly RFCs because of "bouncing footers". Rule 4 480 includes the footer in the line count, but Rule 3 permits the 481 number of lines per page to vary (as seen in several existing 482 RFCs). In that case, the footer (which always contains visible, 483 non-blank characters, as specified by Rule 12 in Section 2.2) 484 "jumps up and down", which is unpleasant to see. Therefore, if 485 and when RFC 2223 is superseded, the RFC Editor should stiffen 486 Rule 3 as follows: 488 o Rule 3A: Each page MUST have exactly the same number of 489 lines, which MUST be limited to (n <=) 58 lines followed by 490 a form feed (FF, ASCII decimal 12) by itself on another line 491 (line n+1). 493 UGLI, as illustrated by this I-D, enables the RFC author to 494 follow an even stiffer version of the rule: 496 o Rule 3B: Each page MUST have exactly 59 lines, where the 497 59th line contains only the characters FF, CR, and LF, in 498 that order. 500 If the author chooses to "repair" page 1 (as explained in step 501 "B" in Section 5.4), then Rule 3 effectively becomes restated 502 as follows: 504 o Rule 3C: Page 1 MUST begin with a blank line and have 505 exactly 60 lines. All other pages MUST have exactly 59 506 lines. The 60th line of page 1 and the 59th line of other 507 pages contain only FF, CR, and LF, in that order. 509 2.1.3 ASCII Characters 511 Rule 1 means that all the character codes in an RFC text file 512 must be from the ASCII set defined in [ANSI]. The set of 128 513 ASCII codes includes the 33 control characters shown in Table 1 514 and the 95 graphic characters shown in Table 2. 516 ------------------------------------------------------------------ 517 Table 1. ASCII Control Characters 519 Dec Chr Meaning Dec Chr Meaning 520 --- --- --------------- --- ---- --------------- 521 000 NUL null 016 DLE dev link esc 522 001 SOH start header 017 DC1 dev ctrl 1 523 002 STX start text 018 DC2 dev ctrl 2 524 003 ETX end text 019 DC3 dev ctrl 3 525 004 EOT end of transmit 020 DC4 dev ctrl 4 526 005 ENQ enquiry 021 NAK negative ack 527 006 ACK acknowledge 022 SYN sync idle 528 007 BEL bell (beep) 023 ETB end trans block 529 008 BS back space 024 CAN cancel 530 009 HT horiz tab 025 EM end medium 531 010 LF line feed 026 SUB substitute 532 011 VT vert tab 027 ESC escape 533 012 FF form feed 028 FS cursor right 534 013 CR carriage ret 029 GS cursor left 535 014 SO shift out 030 RS cursor up 536 015 SI shift in 031 US cursor down 537 127 DEL delete 538 ------------------------------------------------------------------ 539 The control characters were designed for operating remote 540 teletype equipment. (RFC 854 [R854] discusses the function of 541 some these characters in the context of the TELNET network 542 virtual terminal.) Rules 2 and 3 require the FF, CR, and LF 543 characters; and Rule 5 prohibits some types of typography that 544 would use the BS character. Other than that, RFC 2223 does not 545 mention control characters or possible "rogue" uses that would 546 clearly be inappropriate in an RFC. For example, what if 547 someone wants to have fun by including the BEL character? That 548 would not "meet the constraints of a wide variety of printing 549 and display equipment". 551 So, if and when RFC 2223 is superseded, the RFC Editor should 552 consider this stiffened version of Rule 5: 554 o Rule 5A: Except for CR and LF at the end of each line, and 555 FF on the last line of each page, each character MUST be one 556 of the 95 ASCII graphic characters (which are shown in Table 557 2 with the decimal values of their ASCII codes). 559 ------------------------------------------------------------------ 560 Table 2. ASCII Graphic Characters 562 Dec Char Dec Char Dec Char Dec Char Dec Char Dec Char 563 --- ------- --- ------ --- ------ --- ------ --- ------ --- ---- 564 032 [space] 048 0 064 @ 080 P 096 ` 112 p 565 033 ! 049 1 065 A 081 Q 097 a 113 q 566 034 " 050 2 066 B 082 R 098 b 114 r 567 035 # 051 3 067 C 083 S 099 c 115 s 568 036 $ 052 4 068 D 084 T 100 d 116 t 569 037 % 053 5 069 E 085 U 101 e 117 u 570 038 & 054 6 070 F 086 V 102 f 118 v 571 039 ' 055 7 071 G 087 W 103 g 119 w 572 040 ( 056 8 072 H 088 X 104 h 120 x 573 041 ) 057 9 073 I 089 Y 105 i 121 y 574 042 * 058 : 074 J 090 Z 106 j 122 z 575 043 + 059 ; 075 K 091 [ 107 k 123 { 576 044 , 060 < 076 L 092 \ 108 l 124 | 577 045 - 061 = 077 M 093 ] 109 m 125 } 578 046 . 062 > 078 N 094 ^ 110 n 126 ~ 579 047 / 063 ? 079 O 095 _ 111 o 580 ------------------------------------------------------------------ 582 2.1.4 Blank Lines 584 Rule 6 is incomplete or imprecise. A blank line is needed not 585 only between two paragraphs but also between a heading and a 586 paragraph, between an exhibit and a paragraph, and in other 587 places. Also, the term "blank line", if restricted only by Rule 588 2, may be variously interpreted as zero to 72 blank characters 589 (ASCII decimal 32) followed by CR and LF, even though no blank 590 characters are actually needed to display or print a blank 591 line. Therefore, if and when RFC 2223 is superseded, the RFC 592 Editor should consider the following revision of Rule 6: 594 o Rule 6A: A "blank line" is a line containing only two 595 characters: CR and LF. Blank lines are placed as follows: 597 A. The document title, which MAY consist of one or more 598 lines, SHOULD be preceded by two blank lines to separate 599 it from the header of page 1, and SHOULD be followed by 600 two blank lines to separate it from the first heading, 601 which is "Status of This Memo". 603 B. Each heading, regardless of indent level, SHOULD be 604 followed by one blank line. 606 C. Each paragraph of text, regardless of indent level, 607 SHOULD be followed by one blank line. Paragraph text MUST 608 be single-spaced (i.e., there MUST NOT be a blank line 609 between two non-blank lines of the same paragraph). 611 (Other uses of blank lines and other aspects of the format of 612 exhibits are discussed in Section 2.4.) 614 For both display and printing, Word has features for 615 automatically adding blank space for vertical separation. 616 However, this "style" treatment is lost when a Word file is 617 saved as a plain text file. Therefore, UGLI requires authors to 618 manually insert the required blank lines, and this is easily 619 done by striking the return key. 621 2.1.5 Right Page Margin 623 There are good reasons why Rule 7 requires the right page 624 margin to be "ragged", and why Rule 8 prohibits hyphenating 625 words at the right margin. First, studies have shown that text 626 is harder to read when both margins are adjusted than when just 627 the left margin is adjusted, regardless of which font is used 628 or how smoothly blank filler is inserted. Second, when 629 technical text in a fixed-width font is hyphenated at the right 630 margin, the printed result is not only less readable but also 631 ugly (which is not the same as UGLI). 633 2.2 Explicit Requirements for Page Headers and Footers 635 Section 4 of RFC 2223 states the following explicit requirements 636 for page headers and footers, and for page numbers, which are 637 included in the footers: 639 o Rule 9: All pages MUST be numbered consecutively, beginning 640 with "Page 1". (A page's number appears in the page's footer, 641 as specified in Rule 12 below). 643 o Rule 10: Page 1 MUST have a special, multi-line, variable- 644 length header, which is specified in Section 4a of RFC 2223 and 645 illustrated in this I-D. (In UGLI, the RFC author composes page 646 1's header as described here in Section 4.2.) 648 o Rule 11: All pages except page 1 MUST have the same three-line 649 running header, as specified in Section 4b of RFC 2223 and 650 illustrated in this I-D: 652 - RFC 2223 explicitly specifies only the first line of the 653 running header. The first line MUST have "the RFC number on 654 the left (RFC NNNN), the (possibly shortened form) title 655 centered, and the date (Month Year) on the right." 657 - RFC 2223 implies that the running header MUST be three lines 658 long, where the second and third lines are blank. 660 o Rule 12: All pages, including page 1, MUST have three-line, 661 footers that, except for the page number, have identical 662 content, as specified in Section 4c of RFC 2223 and illustrated 663 in this I-D: 665 - RFC 2223 explicitly specifies only the last line of the 666 footer. That line MUST have "the author's last name on the 667 left, category centered, and the page number on the right" 668 in the form "[Page N]". 670 - RFC 2223 implies that the footer MUST be multi-line, with 671 some number of blank lines preceding the last, non-blank 672 line. 674 -- In many RFCs, the footer is four lines long; that is, at 675 least three blank lines always precede the non-blank line 676 that contains the page number. 678 -- In this I-D, the footer is only three lines long, so that 679 at least two blank lines always precede the single non- 680 blank line that contains the page number. Here are some 681 reasons for including only two blank lines in the footer: 683 ---Paragraphs are separated by one blank line. Thus, even 684 if a page is completely full, two blank lines provide 685 sufficient (i.e., visually unambiguous) separation 686 between the last non-blank line of text on a page and 687 the non-blank (i.e., third) line of the footer on that 688 page. (As discussed for enhancement "A" in Section 689 4.5, the last line of text on a page should be the 690 last line of a paragraph or exhibit. It would ugly if 691 it were a heading.) 693 ---The non-blank (i.e., first) line of the running header 694 is normally separated from a page's text by two blank 695 lines (but might sometimes be separated by three blank 696 lines, as discussed in the last paragraph of Section 697 4.5.) So, using two blank lines in the footer lends a 698 pleasingly symmetric appearance to full pages. 700 ---Adding a third blank line to the footer would waste 701 almost 2% of the available text space on many pages. 703 UGLI automatically determines where each page break should be; 704 automatically inserts the 3-line footer for the end of the 705 previous page, including the proper page number; and automatically 706 inserts the 3-line header for the next page. 708 However, the page numbers must be manually copied into the Table 709 of Contents as described in Section 5.4., and the LF characters on 710 the last line must be added later as described in Section 5.5. 712 2.3 Implicit Requirements for Numbering and Indenting 714 RFC 2223 implies the following requirements for numbering sections 715 and for indenting section headings and paragraphs: 717 o Rule 13: Except for some preamble sections and the abstract, 718 sections MUST be decimal numbered in outline style: "1.", 719 "1.1", "1.1.1", etc., as illustrated by this I-D. 721 For both display and printing purposes, Word include features that 722 automatically number sections. However, this "style" treatment is 723 lost when a Word file is saved as a plain text file. Therefore, 724 UGLI requires authors to number sections manually. Some authors 725 will find this laborious, but it is not onerous except in very 726 large, complex documents. Also, it needs to be done only once, 727 when putting on the finishing touches. 729 o Rule 14: Heading indents: Headings MUST be step-indented as 730 follows, as illustrated by this I-D: 732 1-st level heading (i.e., numbered "N.") is flush left. 733 2-nd level heading (i.e., "N.N") is indented 3 spaces. 734 i-th level heading is indented 3*(i-1) spaces. 736 o Rule 15: Paragraph indents: Paragraphs MUST be step-indented as 737 follows, as illustrated by this I-D: 739 1-st level paragraph (under "N." heading) is indented 3 spaces. 740 2-nd level paragraph (under "N.N") is indented 6 spaces. 741 i-th level paragraph is indented 3*i spaces. 743 Word has features to automatically indent headings and paragraphs. 744 However, this "style" treatment is lost when a Word file is saved 745 as a plain text file. Therefore, UGLI requires that an author 746 manually insert nroff requests to indent headings and sections, 747 before the Word file is saved as text. This is the most ugly 748 aspect of UGLI, but it is mitigated by having Word's automatic 749 indenting features available as a powerful "visual guide" that 750 makes it easier for you to do these manual insertions correctly 751 the first time. 753 2.4 Other Requirements 755 RFC 2223 neither explicitly specifies nor clearly implies format 756 requirements for many kinds of typograpical devices that are 757 commonly found in RFCs. This section discusses three of these: 758 bullet paragraphs, content tables, and exhibits. This section also 759 comments on requirements beyond formatting. 761 2.4.1 Bullet Paragraphs 763 RFC 2223 specifies no format for "bullet" paragraphs, and no 764 style predominates in "recent RFCs". The bullet styles used in 765 this I-D are acceptable, but bullets that go deeper than two 766 levels (e.g., those shown four levels deep under Rule 12) can 767 be annoying ... and ugly. In any case, an RFC should be 768 internally consistent in its use of bullets. 770 Word has features to automatically add bullets to paragraphs. 771 However, this "style" treatment is lost when a Word file is 772 saved as a text file. UGLI requires that an author insert 773 bullets manually. This is not onerous; as described in Section 774 4.2, it takes only a few keystrokes for each bullet paragraph. 776 2.4.2 Content Tables 778 RFC 2223 implies that an RFC MUST include a "Table of Contents" 779 section but specifies no format for it, and no style 780 predominates in "recent RFCs". Word has features to 781 automatically generate the table, but some or all of the 782 automatically generated material is lost when the file is saved 783 as text. Also, page numbers are likely to be different after 784 the nroff processing in Phase 3 and must be corrected in Phase 785 4. The author probably will do less work overall by 786 constructing the Table of Contents manually. Some authors may 787 find this laborious but, like section numbering, it needs to be 788 done only once when putting on finishing touches. 790 The style used for the Table of Contents in this I-D is 791 acceptable, but an author may prefer to show a greater or 792 lesser number of heading levels. There is a trade-off between 793 including more levels to convey more information and including 794 fewer levels to make it easier to grasp the overall structure 795 of the RFC. Two levels are usually sufficient, but this I-D 796 includes three as an illustration. 798 2.4.3 Exhibits 800 RFC 2223 neither states nor implies rules for formatting 801 exhibits (i.e., for figures, diagrams, or other illustrations; 802 and for tables and other data displays). 804 Rule 14 for indenting headings and Rule 15 for indenting 805 paragraphs create problems for formatting exhibits. For 806 example, each exhibit could be indented to align with the 807 paragraph that refers to it, but that could be visually choppy. 808 There does not seem to be a nice style that avoids all 809 problems. For example, this I-D uniformly indents all exhibits 810 by six spaces, like a second-level paragraph, but such an 811 exhibit can be at most 66 characters wide (72-character line 812 length minus 6-character indent). So, in an exhibit like 813 Fragment 2, this I-D is unable to show all 72 characters from a 814 line of its own nroff input file (catch 72?); some blanks must 815 be squeezed out. 817 If and when RFC 2223 is superseded, the RFC Editor should 818 consider including these format recommendations: 820 o Each set of exhibits of the same type SHOULD be numbered 821 sequentially. 823 o Each exhibit SHOULD be followed by one blank line. (This 824 extends Rule 6A.) 826 o Each exhibit SHOULD begin with a title line. The title line 827 SHOULD include the exhibit's number and MAY be centered, as 828 illustrated in this I-D. 830 o One blank line SHOULD separate an exhibit's title from the 831 exhibit's body. (This also extends Rule 6A.) 833 o When it is necessary to make clear which lines belong to an 834 exhibit and which belong to the surrounding text (e.g., see 835 Fragment 2), the exhibit SHOULD have a delimiter line at its 836 top and at its bottom (i.e., before the title and after the 837 body). In that case, all other exhibits in the document also 838 SHOULD have delimiter lines. All delimiter lines SHOULD be 839 identical. 841 o Additional content tables MAY be provided for exhibits 842 (e.g., Table of Figures, Table of Tables) if the author 843 believes this would be useful to readers. This I-D provides 844 such tables as illustrations. 846 2.4.4 Terminology 848 Finally, consistency in ISPDs means more than just consistent 849 format; consistent terminology is equally or more important. To 850 avoid confusion, all ISPDs SHOULD use the same term or 851 definition whenever the same concept is mentioned. To improve 852 international understanding, ISPDs SHOULD use terms in their 853 plainest, dictionary sense. ISPDs SHOULD use terms established 854 in standards documents and other well-founded publications and 855 SHOULD avoid substituting private or newly made-up terms. For 856 guidance, authors should see available glossaries [R1208, 857 R1983, Shir]. 859 3. The Word View 861 In UGLI Phase 1, you use Word to compose your RFC like you would any 862 document. By configuring Word for page dimensions, indenting, headers 863 and footers, and other features of RFC format, you can approximate 864 the appearance of a finished RFC and, therefore, see what the final 865 UGLI product will look like while you are still working just in Word. 867 Section 2 has described RFC format in detail, and this section 868 suggests how to configure Word for that format. (Actually, this 869 section describes how the author configures Word 98 on his Macintosh, 870 but the description should apply directly to other versions of Word.) 872 o Page width: Set the font to 10-point Courier with normal spacing; 873 this yields 12 characters per inch. Set the line length to 6 874 inches; this yields 72 characters per line. For example, in Page 875 Setup, select "Letter (Small)" and set left and right margins at 876 1.25 inches each. 878 o Page height: Define the special header for page 1, the 3-line 879 running header for the other pages, and the 3-line footer for all 880 pages. Then set the top and bottom margins to yield 58 lines per 881 page beginning with the first, non-blank line of the running 882 header and ending with the last, non-blank footer line. For 883 example, in Word's Page Setup, set the top margin at 1.17 inches 884 and the bottom at 1.00 inch, and set "From Edge" to 0.75 inch for 885 the header and 0.5 inch for the footer. 887 o Text spacing and alignment: Select "single" line spacing. Set Word 888 to align (i.e., justify) text only on the left margin. Turn off 889 automatic hyphenation. 891 o Indenting and centering: Define and apply "styles" that do 892 automatic indenting for each level of heading, paragraph, and 893 bullet paragraph that you use, with hanging indents for bullet 894 paragraphs. Use 0.25 inch for each 3 characters of required 895 indentation. Define a centered style for, or individually apply 896 centering to, the main title at the top of page 1 and the titles 897 of exhibits. 899 o Pagination enhancement: Turn off "widow and orphan" control. If 900 you intend to enhance pagination as described in Section 4.5, 901 apply "keep together" to exhibits and apply "keep with next" to 902 heading styles. 904 4. The nroff View 906 This section describes how UGLI uses nroff to generate the RFC 907 format. This is illustrated with fragments from the nroff input file 908 used to produce this I-D. Commands in the nroff language are called 909 "requests". Requests consist of a period (".", in column 1) and two- 910 character alphabetic codes, sometimes followed by parameters. 912 4.1 Basic Formatting 914 The first five lines of the nroff input file for this I-D contain 915 the requests shown in Fragment 1. The requests implement the rules 916 for RFC page length, line length, and hyphenation. (In Figure 1, 917 the two-character escape sequence, \", begins a comment that 918 continues to the end of that line. In this fragment and those that 919 follow, the comments are not necessary for the nroff formatting 920 and can be omitted from the nroff input file.) 922 ------------------------------------------------------------------ 923 Fragment 1. Specifying Basic Formatting 925 .pl 10.0i \" Set page length. 926 .ll 7.2i \" Set length of lines. 927 .lt 7.2i \" Set length of 3-part titles in headers and footers. 928 .hy 0 \" Turn off hyphenation of words at right margin. 929 .ad l \" Adjust left margin but not right margin. 930 ------------------------------------------------------------------ 932 4.1.1 Page Length 934 The nroff request ".pl 10.0i" sets the page length to 10.0 935 inches. 937 Why does it say exactly 10.0 inches? Because on this author's 938 machine, that value (in combination with the ".wh" request 939 described below in Section 4.3) produces 58 lines for each page 940 of the nroff output file, beginning with the non-blank line of 941 the header and ending with the non-blank line of the footer. To 942 those 58 lines, UGLI later adds (see Section 5.5) a 59th line 943 that contains only a form feed (as Rule 3 requires). 945 Depending on how nroff's default output font and printer device 946 parameters are set on your machine, "your actual mileage may 947 vary". If so, adjust the parameter values on the ".pl" and 948 ".wh" requests until you get 58 lines per page. 950 4.1.2 Line Length 952 The nroff request ".ll 7.2i" (i.e., 7.2 inches) sets the line 953 length for a full line of text, i.e., a line constructed with 954 no indent (see ".in 0" see in Section 4.4 below). 956 Why does it say exactly 7.2 inches? Because on this author's 957 machine, nroff's default character width is 1/10 inch. Thus, 958 this request sets the maximum line length to 72 characters 959 followed by CR and LF. 961 Depending on how nroff's default output font and printer device 962 parameters are set on your machine, "your actual mileage may 963 vary". If so, adjust the parameter value on this request until 964 you get at most 72 characters per line. For example, your 965 default character width might be 1/12 inch (because 1/10 and 966 1/12 are the most popular settings); if so, use ".ll 6.0i". 968 The nroff request ".lt 7.2i" sets the line length for the 969 three-part titles that are used to create the non-blank lines 970 in headers and footers (see ".tl" requests in Section 4.3). The 971 ".lt" request operates the same way as the ".ll" request. 973 4.1.3 Hyphenation and Adjustment 975 The nroff request ".hy 0" turns off nroff's automatic 976 hyphenation at the right margin (as Rule 8 requires). 978 In nroff, "adjusting" refers to positioning text on a line 979 (with or without "filling" the line, as discussed in Section 980 4.2) and then optionally aligning the text on the left margin, 981 the right margin, both margins, or the center line, including 982 inserting extra blank spaces if needed. 984 The nroff request ".ad l" turns on the "adjusting" function. 985 The parameter "l" (that's a lower case "L") directs that only 986 the left margin should be adjusted (as Rule 7 requires). 988 4.2 Text Filling and First Page Header 990 Fragment 2 shows the next four lines of the nroff input file. 991 These requests turn off nroff's text "filling" function and define 992 the header for page 1. (To be able to indent Fragment 2, some 993 blanks had to be removed from the full, 72-character lines of the 994 header; see page 1 of this I-D for the full-length lines.) 996 ------------------------------------------------------------------ 997 Fragment 2. Specifying First Page Header 999 .nf \" Turn off line-filling function. 1000 Internet Engineering Task Force R. Shirey 1002 Expiration Date: 27 June 2000 27 December 1999 1003 ------------------------------------------------------------------ 1005 The nroff request ".nf" turns off nroff's text "filling" function, 1006 so that the strings of blanks shown in Fragment 2 are preserved in 1007 the output file. 1009 In nroff, "filling" refers to collecting words from text lines of 1010 the input file and assembling them into an output file line (with 1011 exactly one space between each pair of words) until one of the 1012 following conditions occurs: 1014 - Case 1: An end-of-line (in Word, that's a "manual line break" 1015 or a "paragraph mark") is encountered in the input. 1017 - Case 2: Some word does not fit within the line length 1018 established by the ".ll" request described in Section 4.1.2. 1020 In either case, if hyphenation is turned off as it is in this I-D, 1021 then the current output line is terminated, and the next input 1022 word is used to begin the next output line. (In case 2, this input 1023 word is the one that did not fit within the previous line.) 1025 When nroff is run, the filling function is turned on by default. 1026 So, in the nroff input file for this I-D, we place a ".nf" request 1027 just before the layout for the three-line header for page 1, as 1028 shown above in Fragment 2. If we did not turn off the filling 1029 function, nroff would squeeze together the words in the first page 1030 header and output the lines shown in Figure 2. 1032 ------------------------------------------------------------------ 1033 Figure 2. Result of Failure to Turn Off Filling 1035 Internet Engineering Task Force R. Shirey 1036 INTERNET-DRAFT GTE / BBN Technologies 1037 Expiration Date: 22 June 2000 27 December 1999 1038 ------------------------------------------------------------------ 1040 The rest of the nroff input file that follows Fragment 2 keeps the 1041 filling function turned off at all times; that is, the request 1042 ".fi" is not used to turn filling on again. Thus, the only blank 1043 characters (ASCII decimal 32) in nroff's output file for this I-D 1044 are (a) blanks that were explicitly placed in the input file and 1045 (b) leading blanks implied by indenting requests (see ".in" and 1046 ".ti" in Section 4.4) for section headings and paragraphs. 1048 An author may choose to leave the filling function turned on or 1049 off. The advantage of keeping it turned off is that the formatting 1050 seen in nroff's input file is identical to what appears in the 1051 output file. Thus, it is easier to control the appearance of the 1052 output. Pieces of "ASCII art", such as the diagram shown in Figure 1053 3, can be included without having to put ".nf" before each piece 1054 and ".fi" after each piece. The disadvantage of keeping the 1055 filling function off is that nroff does not remove 1056 extraneous spaces like these. You need to find and remove 1057 them yourself, but Word's "Find and Replace" function can help. 1059 ------------------------------------------------------------------ 1060 Figure 3. Sample of "ASCII Art" 1062 +-------------------------+ +---------+ +---------------------+ 1063 |An Attack: | |Counter- | |A System Resource: | 1064 | i.e., A Threat Action | | measure | | Target of Attack | 1065 | +----------+ | | | | +-----------------+ | 1066 | | Attacker |<=================||<========= | | 1067 | | i.e., | Passive | | | | | Vulnerability | | 1068 | | A Threat |<================>||<========> | | 1069 | | Agent | or Active | | | | +-------|||-------+ | 1070 | +----------+ Attack | | | | VVV | 1071 | | | | | Threat Consequences | 1072 +-------------------------+ +---------+ +---------------------+ 1074 ------------------------------------------------------------------ 1076 4.3 Page Breaks 1078 Fragment 3 shows the next eight lines of the nroff input file. 1079 These requests control page breaks, define the header for all 1080 pages except page 1, and define all footers. Comments in Fragment 1081 3 (defined by a two-character escape sequence, \", and including 1082 the characters that follow to the end of a line) are optional. 1084 ------------------------------------------------------------------ 1085 Fragment 3. Specifying Footer, Page Break, and Running Header 1087 .de NP \" Define NP macro. 1088 'sp 2 \" - 2 blank lines. 1089 .tl 'Shirey'GTE / BBN Technologies'[Page %]' \" - 1 non-blank. 1090 .bp \" - Begin page. 1091 .tl 'Internet-Draft'UGLI'1 December 1999' \" - 1 non-blank. 1092 'sp 2 \" - 2 blank lines. 1093 .. \" - End macro def. 1094 .wh -.84i NP \" Set trap for NP. 1095 ------------------------------------------------------------------ 1097 4.3.1 Macro Definition 1099 The first seven lines in Fragment 3 define a macro. The macro 1100 definition has five parts: macro name, footer insertion, new 1101 page beginning, header insertion, and macro termination. 1103 The request ".de" declares the beginning of the macro 1104 definition, and the parameter "NP" (for New Page) assigns a 1105 name to the macro. 1107 The next two requests insert a three-line footer (as Rule 12 1108 requires). The request "'sp 2" inserts two blank lines. Notice 1109 that the control character before the "sp" is an apostrophe 1110 ("'"), not a period ("."). If you want to know why, please read 1111 the manual [Ossa]. 1113 The request ".tl 'Shirey'GTE / BBN Technologies'[Page %]'" 1114 inserts a three-part title line in the current title length 1115 (which is set by the request ".lt" in Fragment 1): 1117 o "Shirey" is left-adjusted. 1118 o "GTE / BBN Technologies" is centered 1119 o A bracketed page number is right-adjusted. (The default 1120 initial page number is "1", but the request ".pn N" can be 1121 used to set the numbering for the next page to N. This can 1122 be useful in assembling an RFC text file from parts that are 1123 processed as separate nroff inputs. 1125 The request ".bp" directs nroff to begin a new page. 1127 The next two requests insert a three-line header (as Rule 11 1128 requires). The request ".tl 'Internet-Draft'UGLI'1 December 1129 1999'" inserts a three-part title line in the current title 1130 length: 1132 o "Internet-Draft" (or "RFC NNNN") is left-adjusted. 1133 o "UGLI" is centered. 1134 o "December 1999" is right-adjusted. 1136 The request "'sp 2" inserts two blank lines, like in the 1137 footer. 1139 The two character sequence ".." terminates the definition of 1140 the macro. 1142 4.3.2 Setting a Trap to Invoke the Macro 1144 The eighth line of Fragment 3 tells nroff when to execute the 1145 NP macro. The request ".wh -.84i NP" sets a trap at a position 1146 0.84 inches above the bottom of each page. 1148 Why exactly 0.84 inches? Because on this author's machine, that 1149 value (in combination with the page length request ".pl 10.0i" 1150 that is discussed in Section 4.1.1) produces exactly 58 lines 1151 on each output page beginning with the non-blank line of the 1152 header and ending with the non-blank line of the footer. 1153 However, "your mileage may vary." If so, adjust the parameters. 1155 Each time that the trap is sprung by having a page become 1156 filled with text down to that position, nroff executes the NP 1157 macro. Also, the ".bp" request on the last line of the nroff 1158 input file, shown in Fragment 4, forces NP to execute so that 1159 that the last page receives a footer. This also places an 1160 extraneous header at the end of the nroff output file, but UGLI 1161 Phase 4 removes that header and does other cleanup tasks, too. 1163 ------------------------------------------------------------------ 1164 Fragment 4. Last Line of nroff Input File 1166 .bp \" Trigger NP macro to insert footer on last page. 1167 ------------------------------------------------------------------ 1169 4.4 Indenting, Centering, and Pagination 1171 In the nroff input file for this I-D, Fragments 3 and 4 are 1172 separated by the body of the draft, i.e., the title, headings, 1173 paragraphs, and exhibits. This section explains nroff requests 1174 that are used to center the main title and the titles of exhibits, 1175 indent headings and paragraphs, and begin a new page when desired. 1176 Figure 4 illustrates these requests. Comments in Figure 4 are 1177 optional and may be omitted. 1179 ------------------------------------------------------------------ 1180 Figure 4. Examples of Centering and Indenting 1182 .in 0 \" Indent all output lines 0 spaces until further notice. 1183 [Two blank lines are placed here to separate the title from the 1184 3-line header on page 1.] 1185 .ce 2 \" Take next 2 input lines and center them in output file. 1186 This Title Line Is Centered 1187 and So Is This One 1188 [Two blank lines are placed here to separate the title from the 1189 first heading on page 1.] 1190 1. A Heading at Level One] 1191 [One blank line here.] 1192 .in 3 \" Indent all output lines 3 spaces until further notice. 1193 [One blank line here.] 1194 A paragraph at level one. 1195 [One blank line here.] 1196 1.1 A Heading at Level Two. 1197 .in 6 \" Indent all output lines 6 spaces until further notice. 1198 [One blank line here.] 1199 A paragraph at level two. 1200 [One blank line here.] 1201 .in 9 \" Indent all output lines 9 spaces until further notice. 1202 .ti 6 \" Indent next output line 6 spaces, then do as before. 1203 o An illustration of how to create a hanging indent by 1204 using the ".ti" request. 1205 [One blank line here.] 1206 .bp \" Begin new major section at the top of a new page. 1207 2. Another Heading at Level One] 1208 [One blank line here.] 1209 ------------------------------------------------------------------ 1211 An nroff request ".in N", where N is an integer, sets the indent 1212 depth to be N spaces from the left margin for lines in the nroff 1213 output file. The setting is "permanent"; it applies to all lines 1214 generated after the request until another ".in" or ".ti" request 1215 is encountered. As shown in Figure 4, the indent for text headings 1216 and paragraphs should be set as specified by Rules 12 and 13 in 1217 Section 2.3. 1219 The ".in 0" request that begins Figure 4 is unnecessary, because 1220 the default initial indent setting is "0". The request is included 1221 here as a reminder to authors that they must properly indent all 1222 lines in the rest of the document. 1224 The nroff request ".ti N" sets the indent depth for the next 1225 output line. The setting is "temporary"; it applies only to that 1226 one line. The lines that follow that line revert to being indented 1227 as specified by the ".in" that was in effect before the ".ti". 1228 This I-D uses ".ti" requests only to create hanging indents for 1229 bulleted and lettered paragraphs and for entries in Section 6, 1230 "References". 1232 The nroff request ".ce N", where N is an integer, centers the next 1233 N input lines within the currently available horizontal output 1234 space, i.e., within the length (72 spaces) specified by the ".ll 1235 7.2i" request in Fragment 1 minus the spaces for the ".in N" that 1236 is currently in effect. 1238 The nroff request ".bp" terminates the current output page and 1239 begins a new page. In this I-D, this action causes the NP macro to 1240 execute as described in Section 4.3, placing a footer on the old 1241 page and a header on the new page. In a large or formal ISPD, the 1242 author MAY place a ".bp" before the level-one heading of each 1243 major section, so that these sections begin on a new page. 1244 However, that style is not often seen in RFCs. 1246 The nroff input file for this I-D has ".bp" requests in the 1247 following places: 1249 A. Before selected level-one headings: 1250 - "Table of Contents" 1251 - "Table of Figures" 1252 - "1. Introduction" 1253 - "2. Format Requirements for RFCs" 1254 - "3. The Word View" 1255 - "4. The nroff View" 1256 - "5. The Five Phases Step-by-Step" 1257 - "6. References" 1259 B. On the last line of the file, to cause the NP macro to place a 1260 footer on the last page, as described for Fragment 4 in Section 1261 4.3.2. 1263 4.5 Pagination Enhancements 1265 Word has a feature that can be used to prevent widows and orphans. 1266 (A "widow" is the last line of a paragraph printed by itself at 1267 the top of a page, and an "orphan" is the first line of a 1268 paragraph printed by itself at the bottom of a page.) If a widow 1269 is about to occur on page, Word prints one less line of text on 1270 the previous page; if an orphan is about to occur, Word moves the 1271 line to the next page. However, this treatment is lost when a Word 1272 file is saved as a plain text file. 1274 RFC 2223 requires neither control of widows and orphans nor other 1275 pagination enhancements. For simplicity, this I-D incorporates 1276 only a few enhancements, and all are made with the nroff request 1277 ".ne", as illustrated by Figure 5. 1279 ------------------------------------------------------------------ 1280 Figure 5. Examples of Keeping Lines Together 1282 .ne 3 \" Keep the next three lines together on the same page. 1283 . Heading at Level One 1284 [One blank line here.] 1285 .in 3 1286 [One blank line here.] 1287 Paragraph at level one. 1288 [One blank line here.] 1289 .ne 3 \" Keep the next three lines together on the same page. 1290 1.1 Heading at Level Two 1291 .in 6 1292 [One blank line here.] 1293 Paragraph at level two. 1294 [One blank line here.] 1295 .ne 6 \" Keep the next six lines together on the same page. 1296 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1297 .ce 1 1298 Exhibit N. Table of Forty Integers 1299 [One blank line here.] 1300 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 1301 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 1302 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1303 [One blank line here.] 1304 ------------------------------------------------------------------ 1306 The nroff request ".ne N" indicates that N more lines are needed 1307 on the current output page. If they are not available, nroff 1308 terminates that output page and begins a new one. In this I-D, 1309 this causes the NP macro to execute as described in Section 4.3, 1310 placing a footer on the old page and a header on the new page. 1312 The enhancements that have been made in this I-D, and are 1313 recommended for UGLI use, are as follows: 1315 A. Each section heading is kept on the same page with at least one 1316 line of text from the paragraph that follows. This is done by 1317 placing a ".ne 3" request before each heading. This indicates 1318 the need for three more lines on the current output page: the 1319 heading line, the blank line that follows the heading, and the 1320 first line of the paragraph. 1322 B. All lines of an exhibit are kept on the same page. This is done 1323 with a ".ne N" request before each exhibit, where N is the 1324 number of lines in the exhibit, including the top and bottom 1325 delimiter lines. 1327 C. Any item in Section 6, "References", that has only two lines is 1328 kept together on the same page by using ".ne 2" (although this 1329 turned out not be necessary in this I-D, as seen on page 35). 1331 D. All the lines of Section 8, "Author's Address", are kept 1332 together on one page (although this turned out not be necessary 1333 in this I-D, as seen on page 35). 1335 Enhancements "A" and "B" are equivalent to using Word's "keep 1336 together" feature. So the nroff output does not differ much from 1337 what is seen with Word's WYSIWYG editor. But widows and orphans 1338 can still occur in the nroff output. More enhancements can be made 1339 with ".ne" requests, but they produce diminishing returns because 1340 the nroff output begins to diverge from what is seen in Word, 1341 giving up some of the "dual-view" advantage of UGLI. For example, 1342 changing "A" to use ".ne 4" and putting ".ne 2" in front of each 1343 of the other paragraphs eliminates orphans, but still leaves ugly 1344 widows like the one on page 22. More work is needed to achieve the 1345 same pagination as Word's "widow and orphan control". 1347 It is possible to construct nroff macros that control widows and 1348 orphans like Word does and make other, more sophisticated 1349 enhancements, too. For example, in the nroff input file for this 1350 I-D, an ".ne 10" request before Figure 1 causes extra, unwanted 1351 blank lines at the bottom of page 6. Trying to eliminate such gaps 1352 by manually rearranging lines of text in the nroff input file 1353 becomes extremely laborious, but a nroff macro in place of ".ne" 1354 could automatically "float" exhibits over text and keep pages 1355 full. Your UNIX environment may already have available sets of 1356 macros that are useful for producing RFCs, and such macros may be 1357 used in Phase 2. 1359 For another example, nroff outputs the last non-blank line of the 1360 last paragraph on page 20 immediately before the two blank lines 1361 of the footer. Therefore, the blank line that follows the 1362 paragraph in the nroff input file is output at the top of page 21, 1363 immediately after the two blank lines of the header, making the 1364 header look like it has three blank lines. A macro could eliminate 1365 such unwanted lines. 1367 5. The Five Phases Step-by-Step 1369 As shown in Figure 6, UGLI has five phases and uses three 1370 intermediate files. This section describes all five phases. Most of 1371 the details for Phases 1 and 2 have already been covered in Sections 1372 2, 3, and 4. This section mainly describes how to move files between 1373 your Word environment and your UNIX environment, how to execute the 1374 nroff command in Phase 3, how to do final editing in Phase 4, and how 1375 to perform the vi operations in Phase 5. (You do not need previous 1376 knowledge of vi; this section provides complete instructions for the 1377 few operations that must be performed.) 1379 ------------------------------------------------------------------ 1380 Figure 6. UGLI Phases and Files 1382 +---------------------------+ 1383 |Infrequent Debugging Cycle | 1384 | +-------------+ | 1385 | | Normal Edit | | 1386 v v Cycle | | 1387 +----------+-----------+ +-----------+ +-----------+ +-----------+ 1388 | 1. Draft | 2. Add | | 3. Run | | 4. Polish | | 5. Run | 1389 | RFC In | nroff Ops | | nroff On | | RFC In | | vi On The | 1390 | MS Word | To File | | Text File | | MS Word | | Text File | 1391 +----------+-----------+ +-----------+ +-----------+ +-----------+ 1392 Perform 1 and 2 as | ^ | ^ | ^ | 1393 Parallel or Serial v | v | v | v 1394 +---------+ | +--------+ | +---------+ | +--------+ 1395 4 Text Files: |nroff | | | nroff | | | vi | | | Final | 1396 3 Interim, |Input |-+ | Output |-+ | Input |-+ | RFC | 1397 and 1 Final |Text File| | File | | File | | File | 1398 +---------+ +--------+ +---------+ +--------+ 1400 ------------------------------------------------------------------ 1402 5.1 Draft Document in Word 1404 In Phase 1, you use Word to compose your document in the RFC 1405 format described in Section 2. As described in Section 3, you can 1406 configure the Word file to closely resemble the appearance of the 1407 RFC format. This enables you to see approximately what the final 1408 product of Phase 5 will look like while you are still working in 1409 Word in Phases 1 and 2. 1411 5.2 Prepare File for nroff Processing 1413 In Phase 2, you create an input file for nroff processing in Phase 1414 3. This includes adding nroff requests and properly saving the 1415 result as text file. 1417 5.2.1 Create a Dual-View File 1419 Section 4 describes how to enhance your Word document with 1420 nroff requests to create RFC formatting after the Word file is 1421 saved as text. The automatic formatting you established in 1422 Phase 1 provides a visual guide for inserting the requests 1423 correctly. (If you have access to a package of nroff macros 1424 that can enhance pagination and perform other functions found 1425 in modern word processors, you can insert those macro calls in 1426 this phase.) 1428 You achieve a "dual view" by formatting nroff requests as 1429 "hidden text" in the Word document. Then, you can turn off the 1430 hidden text in Word whenever you want to view or print a rough 1431 draft directly from Word without going through nroff. 1433 5.2.2 Properly Save As a Text File 1435 Next, save the Word file using the "Text Only with Line Breaks" 1436 option, not the "Text Only" option. In this discussion, we call 1437 the saved file "nroffin", because we use it as nroff's input 1438 file for Phase 3. 1440 The distinction between "Text Only with Line Breaks" and "Text 1441 Only" is important. In Word, the former produces a text file in 1442 which every line that is displayed or printed from the original 1443 Word file results in a separate "line" in the text file, i.e., 1444 in a separate character string with its own CR and LF 1445 characters at the end. 1447 For example, if we view this paragraph of the original Word 1448 file on my screen, we see 13 lines with a "paragraph mark" at 1449 the end of only the 13-th line. If we improperly save the 1450 original Word file as "Text Only", then this multi-line 1451 paragraph in the Word file results in a single "line" in the 1452 nroff input file (i.e., a string of characters terminated by 1453 one CR-LF). So, if we view the improperly saved paragraph in 1454 Word, it looks just like it did in the Word file; it has 13 1455 lines and a paragraph mark at the end of the last line. If we 1456 properly save the file as "Text Only with Line Breaks", the 1457 result is 13 "lines" in the nroff input file. That is, we still 1458 see 13 lines when we view the file in Word, but now each line 1459 ends with a paragraph mark. 1461 This difference affects nroff requests, such as ".in", which 1462 deal with "lines". When nroff processes the properly saved 1463 paragraph, it indents by adding nine blank characters at the 1464 front of each of the 13 "lines" it receives. When nroff 1465 processes the improperly saved paragraph, it adds nine 1466 characters at the front of the single "line" it receives; so 1467 that when we view the paragraph in the nroff output file, only 1468 the first line of the 13 is indented. 1470 5.3 Process File in nroff 1472 In Phase 2, you move the "nroffin" file to a UNIX system, process 1473 it with nroff to create an "nroffout" file, and move "nroffout" 1474 back to where you can work on it some more with Word. 1476 The UNIX host that this author uses for UGLI is his departmental 1477 POP3 host, the one from which Eudora retrieves this author's mail. 1478 The user identifier and password that Eudora uses to retrieve mail 1479 provides a handy account for FTP and TELNET connections and for 1480 running nroff and vi. FTP and TELNET are provided on Macs by the 1481 freeware NCSA Telnet application. Windows users all have FTP and 1482 TELNET available in DOS or may instead use some Windows 1483 application that provides those protocols. 1485 5.3.1 Move nroff Input to UNIX System 1487 There are many ways to move "nroffin" to a UNIX system. If the 1488 machine on which you run Word is not connected to a computer 1489 network, you probably will use sneaker-net and a floppy disk. 1490 But if you have network connectivity and can arrange a login 1491 account on a UNIX host, your work will go much faster. 1493 Run the NCSA Telnet program (or its equivalent on your 1494 platform) and "open" a connection to the UNIX host, checking 1495 the box that says "FTP session" (i.e., open a connection to 1496 port 21 on the host). This initiates a session in which your 1497 local computer is an FTP client, and the UNIX host is the FTP 1498 server. When the host says "ready", reply with "user". When the 1499 host says "Username:", reply with yours. When the host says 1500 "password required", reply with yours. When the host says 1501 "logged in", say "put nroffin". (Your actual dialog may differ 1502 slightly, depending on how your FTP client and server are 1503 implemented.) 1505 This description omits some details and glosses over occasional 1506 frustrations. For example, the FTP client usually requires 1507 "nroffin" to be at the top level of the folder (i.e., 1508 directory) that is the hard disk on which the TELNET 1509 application resides, and that also is where "nroffout" is 1510 placed after being retrieved from the server. NCSA Telnet is 1511 touchy and sometimes fails unless a certain ritual is followed. 1512 Before logging in, look in your local folder for any old 1513 "nroffin" file and drag it to the Trash. Then, drag the new 1514 "nroffin" file from your desktop into that folder. After 1515 logging in but before saying "put", remove any old "nroffin" 1516 from the UNIX host. Do this by first saying "ls", which is a 1517 UNIX command supported in NCSA Telnet to list files in the UNIX 1518 account. If there already is an "nroffin" on the UNIX host, say 1519 "rm nroffin", i.e., "remove" the old file. 1521 Sometimes NCSA Telnet simply refuses to function and, in 1522 response to a "put", complains ("Cannot open file") no matter 1523 what is tried. In such cases, rebooting seems to be the cure. 1525 5.3.2 Run nroff Command 1527 In a separate window, use NCSA Telnet to "open" a TELNET 1528 connection to the same UNIX host (i.e., do not check the FTP 1529 box this time). When the host says "Login:", reply with your 1530 username again. When the host says "Password:", reply with 1531 yours again. When the host prompts for a command, say "nroff 1532 nroffout"; i.e., run nroff and specify "nroffin" as 1533 the input file and "nroffout" as the output file. 1535 5.3.3 Get nroff Output from UNIX System 1537 Finally, return to the first window, where you have the FTP 1538 session, and say "get nroffout". Now you have the nroff output 1539 file back on your local machine, ready for final editing in 1540 Phase 4. 1542 5.4 Do Final Editing and Prepare for vi 1544 In Phase 4, you open "nroffout" with Word and review the result of 1545 the nroff processing. If there are errors to correct or additions 1546 to make, return to Phase 1 or Phase 2. If not, do the following 1547 four steps to polish the draft and get ready for Phase 5: 1549 A. Complete the content tables: Now that you can see which page 1550 each heading and exhibit is on, you write page numbers in the 1551 Table of Contents and in any other content tables you have. 1553 B. (Optional) Add a line to page 1: If you wish, you can correct 1554 the length discrepancy of page 1 that is described in Section 1555 2.1.1. To make all pages display and print identically, add a 1556 blank line to the beginning of the file, i.e., as the first 1557 line of page 1. 1559 C. Insert markers for vi: In this author's environment, when 1560 "nroffout" is viewed in Word, lines equivalent to the four 1561 shown in Fragment 5 appear at each boundary between pages: 1563 ------------------------------------------------------------------ 1564 Fragment 5. Page Boundary in nroff Output File 1566 ] 1567 1568 1569 Internet-Draft UGLI December 1999 1570 ------------------------------------------------------------------ 1572 The first line is the last line of a page: a non-blank footer 1573 line (which always ends with the "]" character after the page 1574 number) and its paragraph mark. The next two lines are empty. 1575 The fourth line is the first line of a page: the non-blank 1576 running header line. We would like to simply replace the second 1577 and third lines by a single line with and save the file as text, achieving the effect shown in 1579 Fragment 6 (where "FF", "CR", and "LF" represents the ASCII 1580 control characters), which would satisfy Rule 3: 1582 ------------------------------------------------------------------ 1583 Fragment 6. Page Boundary in RFC Format 1585 ] 1586 1587 Internet-Draft UGLI December 1999> 1588 ------------------------------------------------------------------ 1590 Unfortunately, Word discards page breaks when it saves a file 1591 as text. But vi does not discard FF characters when it saves a 1592 file. Therefore, we accomplish the change in two steps, one 1593 with Word and one with vi. First, we use Word to delete the 1594 second line and insert "QQQQ" in the third line as a marker for 1595 vi. To do this, use Word's "Replace All" option in "Find and 1596 Replace", replacing character strings as shown Figure 7. 1598 ------------------------------------------------------------------ 1599 Figure 7. "Find" and "Replace" Strings 1601 Before: ]Int 1603 After: ]QQQQInt 1604 ------------------------------------------------------------------ 1606 Now when we view the file in Word, we see the following at each 1607 page boundary: 1609 ------------------------------------------------------------------ 1610 Fragment 7. Page Boundary in vi Input File 1612 ] 1613 QQQQ 1614 Internet-Draft UGLI December 1999 1615 ------------------------------------------------------------------ 1617 The choice of "QQQQ" is not significant to either Word or vi. 1618 You can use any character string that is not used elsewhere in 1619 the file, such as "DSSCS". In the next phase, we will replace 1620 each "QQQQ" string with an ASCII FF control character. 1622 (For this I-D, the character string "QQQQ" *does* appear in the 1623 text, so it is not usable for the substitution marker. Instead, 1624 this author uses the string ... Oops, sorry! If he tells you, 1625 it will be usable.) 1627 D. Remove debris: In this author's environment, "nroffout" usually 1628 has some unwanted lines and fragmentary pages after the last 1629 real page. You use Word to delete everything that follows the 1630 "QQQQ" on the last real page of your RFC. 1632 After these editing steps, you save the Word file as text. This 1633 time, it does not matter whether you save as "Text Only" or "Text 1634 Only with Line Breaks", because every line you see in Word already 1635 has a paragraph mark at its end. We call the saved file "viin", 1636 because we use it as vi's input file for Phase 5. 1638 5.5 Process File in vi 1640 In Phase 5, using the same technique you used in Phase 3, you move 1641 the "viin" file to a host that has vi or a similar line editor 1642 program. In UNIX, you then say "vi viin" to invoke the editor and 1643 open the file, and you type three commands. 1645 A. At vi's prompt, you type ":1,$ s/QQQQ//". That is, 1646 between the second and third slashes, you enter the ASCII FF 1647 control character by striking the "L" key while holding down 1648 the "control" key. This string says, "This (:) is a vi command. 1649 From the first line of the file (1) to the last line ($), 1650 wherever there is the string 'QQQQ', substitute (s) an ASCII 1651 form feed character." 1653 B. Next, type the command ":w viout", which says, "Write the file 1654 to a new file with the name 'viout'." 1656 C. Finally, type the command ":q" to quit (i.e., exit, terminate) 1657 the vi program, and then move "viout" back to your local 1658 machine. 1660 Congratulations! You now have a finished paper that satisfies the 1661 requirements of RFC 2223 ... and then some. 1663 6. References 1665 [ANSI] American National Standards Institute, "Information Systems 1666 --Coded Character Sets--7-Bit American National Standard 1667 Code for Information Interchange (7-Bit ASCII)", ANSI X3.4- 1668 1986 (R1997). 1670 [Hain] T. Hain, Using Microsoft Word to create Internet Drafts and 1671 RFC's, draft-hain-msword-template-00.txt, February 1999. 1673 [Ossa] J. F. Ossanna and B. W. Kernighan, "Troff User's Manual", 1674 AT&T Bell Laboratories Murray Hill, NJ 07974, Computing 1675 Science Technical Report No. 54, revised Nov 1992. 1677 [R854] J. Postel, "TELNET Protocol Specification", RFC 854, May 1678 1983. 1680 [R1208] O. Jacobsen and D. Lynch, "A Glossary of Networking Terms", 1681 RFC 1208, Mar 1991. 1683 [R1983] G. Malkin, ed., "Internet Users' Glossary", FYI 18, RFC 1684 1983, Aug 1996. 1686 [R2026] S. Bradner, "The Internet Standards Process -- Revision 3", 1687 RFC 2026, BCP 9, Oct 1996. 1689 [R2119] S. Bradner, "Key Words for Use in RFCs To Indicate 1690 Requirement Levels", BCP 14, RFC 2119, Mar 1997. 1692 [R2223] J. Postel and J. Reynolds, "Instructions to RFC Authors", 1693 Oct 1997. 1695 [Shir] R. Shirey, "Internet Security Glossary", , 17 Oct 1999. 1698 7. Security Considerations 1700 This paper does not discuss security issues and has no security 1701 implications of which the author is aware. 1703 8. Author's Address 1705 Please address all comments to: 1707 Robert W. Shirey GTE / BBN Technologies 1708 Email: rshirey@bbn.com Suite 1200, Mail Stop 30/12B2 1709 Phone: +1 (703) 284-4641 1300 Seventeenth Street North 1710 Fax: +1 (703) 284-2766 Arlington, VA 22209-3801 USA 1712 9. Expiration Date 1714 This Internet Draft expires on 27 June 2000.