Internet Draft J. Postel
RFC Editor
Category: Informational USC ISI
Expires April 2007 October 25, 2006
Nroff Template for Internet Drafts and RFCs
Status of this Memo
Distribution of this memo is unlimited.
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
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/1id-abstracts.html
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
This file is a template for preparing an nroff source file for an
Internet Draft or an RFC. It contains instructions for applying nroff
to this file to create a correct Internet Draft. It also describes the
simple nroff subset used for markup by the RFC Editor, as well as some
style tips.
Postel, Braden Expires April 2007 [Page 1]
Internet Draft 2-nroff.template October 25, 2006
Table of Contents
1. Introduction ....................................................2
2. Using Nroff .....................................................2
2.1. Features Used by RFC Editor ................................2
2.2. Formatting End of Page .....................................4
3. Security Considerations .........................................4
4. IANA Considerations .............................................4
5. Appendix A: "C" Program for Pagination ..........................5
6. References ......................................................6
1. Introduction
This document is a template for preparing an nroff source file for an
Internet Draft or an RFC. It contains instructions for applying
nroff to this file to create a correct Internet Draft.
This document summarizes and embodies the simple nroff subset that is
used for markup by the RFC Editor, and it provides guidelines for
authors who are able to submit nroff source to the RFC Editor. This
document also includes some RFC style guidelines in addtion to those
listed in http://www.ietf.org/ietf/1id-guidelines.html.
With very rare exceptions, an RFC should begin with an Introduction
section that is numbered 1. The introduction should provide enough
background so that any reasonably informed Internet person can
quickly and clearly understand the purpose, scope, and assumptions
behind the document. This may require some *brief* background beyond
that required by a person working directly on this particular
technical topic.
2. Using Nroff
2.1. Features Used by RFC Editor
The RFC Editor generally uses the simplest nroff features, basically
the "-ms" macro package and the following few basic nroff directives:
DIRECTIVE FUNCTION
.ce Center following line.
.ti # 'temporary indent' -- # is number of spaces.
Indents only the line immediately following.
.in # Change indentation to # spaces
Postel, Braden Expires April 2007 [Page 2]
Internet Draft 2-nroff.template October 25, 2006
.nf 'No fill': begin block of text to be displayed.
.fi Fill (i.e., left-justify, line wrap)
.ne # 'need' -- Keep following # lines on same page
.bp Break page
.br Break line
.KS 'Keep Start' -- lines up to .KE on same page
.KE 'Keep End' -- end of 'keep' block
Nroff also has a '.sp' (space) directive to insert a blank line.
However, it is far easier (and more readable) to use the fact that
each blank line in the nroff source creates a blank line in the
output.
Nroff includes many variations on the trivial commands shown above.
For example, indentation can be specified relative to the current
indentation, using '.in +#' or '.in -#'. Authors are welcome to use
such features, but for simplicity this template uses only the
simplest set of commands.
Some authors who are proficient in nroff will wish to use more
advanced features, including perhaps their own macros. This is a
private matter for the author, unless and until the document is
submitted to the RFC Editor for publication as an RFC. Upon document
submission, the RFC Editor will request the nroff source, if any. If
the source is sufficiently straightforward, it will be used by the
RFC Editor to speed the publication process. If not, the RFC Editor
will generate a new nroff source, generally using the simple subset
above.
The considerations here are as follows:
o Defined macros (beyond the -ms package) must be in-line at the
front of the source. The RFC Editor is currently prepared to
maintain only one source file for each published RFC.
o Some of the editors are not nroff experts, and even those who
may be do not have the time to figure out some complex/obscure
macro. If any special knowledge about these macros is needed
to modify the text for editorial purposes, the RFC Editor will
find it more expedient to generate a new .nroff source for the
document.
Postel, Braden Expires April 2007 [Page 3]
Internet Draft 2-nroff.template October 25, 2006
o The RFC Editor does not keep a distinct Make file for each RFC,
so it is not helpful to send us a tar file or shar script that
magically makes a directory and builds an RFC. Our primary
input is a .txt file, with a .nroff file as a possible
secondary input. When the RFC is published, the RFC Editor
will archive a .txt file and a corresponding .nroff file.
In other words, keep it simple and you can help us a lot; don't show
off your programming prowess and waste our time.
2.2. Formatting End of Page
The Unix command to create a formatted Internet Draft is:
"nroff -ms input-file.nroff > output-file.txt"
However, nroff will not follow the RFC standard format for a page: a
Form feed (FF or Control-L)) after the last visible line on the page
and no extra line feeds before the first visible line of the next
page. We want:
last visible line on page i
^L
first visible line on page i+1
We invented hacks to fix this. The original hack was a "sed" script
that called a "C" program called "pg". More recently, we have been
using a simple Perl script (see Appendix A). Then the command to
process the nroff source file becomes:
nroff -ms input-file.nroff | fix.pl > output-file.txt
For example:
nroff -ms 2-nroff.template | fix.pl > 2-nroff.template.txt
3. Security Considerations
There are no security considerations relevant to this document.
4. IANA Considerations
No actions are required from IANA as result of the publication of
this document.
Postel, Braden Expires April 2007 [Page 4]
Internet Draft 2-nroff.template October 25, 2006
5. Appendix A: "Perl" Script for Pagination
#! /local/bin/perl
# fix.pl 17-Nov-93 Craig Milo Rogers at USC/ISI
#
# The style guide for RFCs calls for pages to be delimited by the
# sequence .
# Unfortunately, NROFF is reluctant to produce output that conforms to
# this convention. This script fixes RFC-style documents by searching
# for the token "FORMFEED[Page", replacing "FORMFEED" with spaces,
# appending a formfeed line, and deleting white space up to the next
# non-white space character.
#
# There is one difference between this script's output and that of
# the "fix.sh" and "pg" programs it replaces: this script includes a
# newline after the formfeed after the last page in a file, whereas the
# earlier programs left a bare formfeed as the last character in the
# file. To obtain bare formfeeds, uncomment the second substitution
# command below. To strip the final formfeed, uncomment the third
# substitution command below.
#
# This script is intended to run as a filter, as in:
#
# nroff -ms input-file | fix.pl > output-file
#
# When porting this script, please observe the following points:
#
# 1) ISI keeps perl in "/local/bin/perl"; your system may keep it
# elsewhere.
# 2) On systems with a CRLF end-of-line convention, the "\n"s below
# may have to be replaced with "\r\n"s.
$* = 1; # Enable multiline patterns.
undef $/; # Read whole files in a single
# gulp.
while (<>) { # Read the entire input file.
s/FORMFEED(\[Page\s+\d+\])\s+/ \1\n\f\n/g;
# Rewrite the end-of-pages.
# s/\f\n$/\f/; # Want bare formfeed at end?
# s/\f\n$//; # Want no formfeed at end?
print; # Print the resultant file.
}
6. References
Postel, Braden Expires April 2007 [Page 5]
Internet Draft 2-nroff.template October 25, 2006
6.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, October 2005.
6.2. Informative References
[2223BIS] Reynolds, J. and R. Braden, "Instructions to Request for
Comments (RFC) Authors", draft-rfc-editor-rfc2223bis-
08.txt, August 2004.
Authors' Addresses
Jon Postel
Former Address:
USC Information Sciences Institute
Current Address:
Unknown (but we are hopeful)
EMail: postel@isi.edu (known to be a black hole)
RFC Editor
USC Information Sciences Institute
4676 Admiralty Way
Marina del Rey, CA 90292-6695
Tel: 310 448 9369 (Sandy Ginoza)
Tel: 310 448 9173 (Bob Braden)
EMail: rfc-editor@rfc-editor.org
Postel, Braden Expires April 2007 [Page 6]
Internet Draft 2-nroff.template October 25, 2006
Full Copyright Statement
Copyright (C) The IETF Trust (2006).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, 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
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 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.
Postel, Braden Expires April 2007 [Page 7]