Home > RFC Editor Tutorial -- ��How to Write an RFC��

RFC Editor Tutorial -- ��How to Write an RFC��

Page 1
31 Jul 05 1
RFC Editor Tutorial -- ��How to Write an RFC��
IETF-63 Paris, France
31 July 2005

Page 2
31 Jul 05 RFC Editor 2
Goals of this Tutorial
∎ Introduction to the RFC process for
∎ Hints for old hands.
∎ Improve quality of product ∎ Hasten publication
∎ Review some important editorial
policies and formatting rules – Gotchas.

Page 3
31 Jul 05 RFC Editor 3
∎ Grateful acknowledgment: Avri Doria��s slides
from IETF 61 were our starting point.
∎ No time to explain everything in detail ∎ See references, especially:

Page 4
31 Jul 05 RFC Editor 4
Overview of this Tutorial
∎ Background: The RFC Series and the RFC Editor ∎ The Publication Process ∎ How to Write an RFC

Page 5
31 Jul 05 RFC Editor 5
∎ The RFC Editor
∎ A (very short) history lesson – Jon Postel ∎ The RFC Editor today
∎ The RFC Series
∎ Relation to the IETF ∎ Independent submissions

Page 6
31 Jul 05 RFC Editor 6
Historical Context of RFC Series
∎ Short chronology of Internet technology:
∎ 1969-1983: ARPAnet protocol development
∎ NCP, Telnet, FTP, SMTP
∎ 1975-1985: Internet protocol development
∎ IP, TCP, RIP, ARP, DNS, ��
∎ 1985-1990: NSFnet ∎ 1991-today: Commercial Internet
∎ HTTP protocol

Page 7
31 Jul 05 RFC Editor 7
∎ RFC document series
∎ Begun by Steve Crocker [RFC 3] and Jon Postel in 1969. ∎ Informal memos, technical specs, and much more.
∎ Jon Postel quickly became the RFC Editor.
∎ 28 years: 1970 until his death in 1998. ∎ Postel had an enormous influence on the developing
ARPAnet & Internet protocols – known as the ��Protocol Czar�� and the ��Deputy Internet Architect��.
∎ He established and maintained the consistent style and
editorial quality of the RFC series.
∎ Jon was a 2-finger typist.

Page 8
31 Jul 05 RFC Editor 8
Jon Postel
Newsweek Aug 8, 1994 Photo by Peter Lothberg – IETF34 Aug 1995

Page 9
31 Jul 05 RFC Editor 9
Jon Postel��s Playful Side
∎ April 1 RFCs
∎ A little humorous self-parody is a good thing�� ∎ Most, but not all, April 1 RFCs are satirical documents.
∎ We expect you can tell the difference ;-)
∎ April 1 submissions are reviewed for cleverness,
humor, and topical relation to IETF themes.
∎ Avian Carriers is famous [RFC 1149] ∎ The Evil Bit is my favorite [RFC 3514]

Page 10
31 Jul 05 RFC Editor 10
The RFC Editor today
∎ A small group at Jon��s long-term home,
∎ the Information Sciences Institute (ISI) of USC. ∎ ~5 FTEs
∎ Funded by ISOC. ∎ Current leadership:
∎ Joyce Reynolds, Postel��s chief editorial assistant 83-98. ∎ Bob Braden, colleague of Postel 1970-1998. ∎ Aaron Falk, relative newcomer.

Page 11
31 Jul 05 RFC Editor 11
The RFC Series
∎ Earliest document series to be published online. ∎ 1969 – today: 36 years old. ∎ 4100+ documents. ∎ An ARCHIVAL series: RFCs are forever! ∎ A nearly-complete record of Internet technical
∎ Early RFCs: a treasure trove of technical history. ∎ Many ��wheels�� that we repeatedly re-invent.

Page 12
31 Jul 05 RFC Editor 12
RFC Publication Rate

Page 13
31 Jul 05 RFC Editor 13
RFCs and the IETF
∎ It was natural to adapt the RFC series to
publication of Internet standards documents.
∎ The RFC Editor is therefore one component of the
standards process, under IAB supervision.[RFC 2026]
∎ An RFC Editorial Board drawn from IETF
community provides advice and counsel to the RFC Editor, particularly about independent submissions.

Page 14
31 Jul 05 RFC Editor 14
The Internet Standards process
∎ RFC 2026 rules. ∎ It defines document maturity levels:
∎ Standards track: Proposed, Draft, Standard. ∎ Non-standards track: Experimental, Informational,
∎ Not quite either: Best Current Practice.
∎ Shown on RFC header as ��Category:��
∎ Except, one category ��Standards Track��
∎ A published RFC can NEVER change, but its category
can change (see rfc_index.txt).

Page 15
31 Jul 05 RFC Editor 15
Two Sources for RFCs
∎ IETF submissions
∎ Mostly from Working Groups. ∎ A few are individual submissions via the IESG. ∎ All are submitted to the RFC Editor by the IESG, after
approval and with announcement to community.
∎ RFC Editor (��independent��) submissions
∎ Submitted directly to RFC Editor. ∎ IESG review for conflict with IETF activity, make
publish/do-not-publish recommendation. RFC Editor has final decision, with advice from Editorial Board.
∎ Only Experimental or Informational category.

Page 16
31 Jul 05 RFC Editor 16
Some Common Questions
∎ Why does every RFC say ��Network Working
Group�� at the top?
∎ A reminder of our history [RFC 3] (1969).
∎ ��I want to read RFC 219, but the index says ��not
∎ The early archive (RFCs 1-800) did not survive the
changeover from TOPS20 to Unix around 1983.
∎ Volunteers have been retyping early RFCs. ∎ There are still about 80 that have not been typed and
proof-read. (This effort on hold for several years.)

Page 17
31 Jul 05 RFC Editor 17
More Common Questions
∎ Why do Internet Drafts expire after 6 months?
∎ Experience with RFCs in the early days showed the
value of having ONE archival series, the RFC series. To avoid accidentally creating a competing archival series, the early IAB made I-Ds expire.
∎ There has been much heated discussion about whether
this is still a good idea.
∎ Why does the RFC Editor publish independent

Page 18
31 Jul 05 RFC Editor 18
Why Independent Submissions (1)?
1. Document proprietary protocols

Encourage companies to publish their protocol designs

Socially desirable behavior��
2. Republish output of other standards bodies, to make it easily available to Internet community.

More socially-desirable behavior

Page 19
31 Jul 05 RFC Editor 19
Why Independent Submissions (2)?
3. Repository of technical history

To record important new ideas, including perhaps controversial ideas.

Should follow norms of academic publication, including in-depth motivation and analysis of previous work in the field.

Hopefull, can help to counter possible ossification of the IETF technical discourse.

Page 20
31 Jul 05 RFC Editor 20
Why Independent Submissions (3)?
4. Document minority views in WG discussions

This may (or may not) justify publication.

Must be very clear about its intent and status as road- not-taken.

RFC Editor listens carefully to what WG chairs and IESG say.

When WG is active, IESG can say ��[Please] Do Not Publish Now��, providing up to 1.5 years pub delay.

Page 21
31 Jul 05 RFC Editor 21
The RFC Editor Web site
∎ Search engines for RFCs, Internet Drafts ∎ RFC publication queue ∎ Master index to RFCs: rfc-index.html, .xml ∎ ��Official Internet Protocols Standards�� list ∎ Errata ∎ Policy changes, news, ��

Page 22
31 Jul 05 RFC Editor 22
RFC Publication Process
∎ Overview ∎ Queue states ∎ AUTH48 procedure ∎ Contents of an RFC

Page 23
31 Jul 05 RFC Editor 23
RFC Sub-Series
∎ All RFCs are numbered sequentially. ∎ There was a desire to identify significant subsets
of RFCs – Postel invented ��sub-series��. Some RFCs have a sub-series designator and number.
∎ E.g., ��RFC 2026, BCP 9��
∎ Subseries designations:
Best Current Practice category
Standard category
Informational: user documentation

Page 24
31 Jul 05 RFC Editor 24
STD Sub-Series
∎ Originally: all protocols expected to reach
Standard category and enter STD sub-series.
∎ STD sub-series were overloaded to represent
��complete standards��.
∎ Multiple RFCs can be included in one STD.
∎ STD 5 = ��IP�� includes RFCs 791, 792, 919, 922, 950, 1112 ∎ STD 13 = ��DNS��, includes RFCs 1034, 1035 ∎ STD 12 = ��Network Time Protocol��, currently no RFCs.
∎ See: www.rfc-editor.org/rfcxx00.html#STDbySTD for
complete list.

Page 25
31 Jul 05 RFC Editor 25
STD Subseries and ISDs
∎ Postel��s idea was that protocols evolve, so RFC
numbers make confusing names for protocols. He adapted STD numbers as effectively protocol names.
∎ And reality is increasingly complicated!
∎ The IESG (who assigns STD numbers) does not follow
Jon��s intent for STDs.
∎ We need a better way. The newtrk proposal, an
ISD (Internet Standards Document), could be the better way.

Page 26
31 Jul 05 RFC Editor 26
Publication Process: Overview (1)
∎ First published as an Internet Draft
∎ Send us the nroff or xml2rfc source, if available.
∎ RFC Editor
∎ Copy-edits for clarity, syntax, punctuation, �� ∎ Creates official nroff source containing editorial changes ∎ Makes many consistency checks
∎ IANA acts on IANA Considerations
∎ Creates new registries, assign numbers, informs RFC Editor ∎ RFC Editor plugs assigned numbers into document.

Page 27
31 Jul 05 RFC Editor 27
Publication Process: Overview (2)
∎ Publication may be held up by other RFCs.
∎ ��REF�� state: doc set linked by Normative refs must be
published simultaneously.
∎ An RFC # is assigned. ∎ Document and diff file sent to authors for final check
∎ ��AUTH48�� state. ∎ All named authors are responsible.
∎ Finished document added to archive and index.
∎ Announcement on ietf-announce list. ∎ .nroff files archived, for later revision.

Page 28
31 Jul 05 RFC Editor 28

Page 29
31 Jul 05 RFC Editor 29

Page 30
31 Jul 05 RFC Editor 30
The RFC Editor Does Edit ��
∎ At least, for correct syntax and punctuation. ∎ Ideally, to improve clarity, consistency, and quality
of the prose.
∎ To maintain consistent format and style.
∎ Using the format and style that many, many years of
experience have been found to work well.

Page 31
31 Jul 05 RFC Editor 31
The RFC Editor checks many things

Header format and content

Title format

Abstract length and format

Table of Contents

Presence of required sections

No uncaught IANA actions

Spelling checked

ABNF/MIB/XML OK, using algorithmic checker

Citations match references

Most recent RFC/I-D cited

Pure ASCII, max 72 char lines, hyphens, etc.

Header and footer formats

��Widows�� removed

References split into Normative, Informative

Boilerplate OK

Page 32
31 Jul 05 RFC Editor 32
AUTH48 State: Final Author Review
∎ Authors given rfcxxxx.txt file and diff file (.html) ∎ Last-minute editorial changes allowed – But should not be
technically substantive or too extensive.

Else, must get OK from AD, WG chair.
∎ This process can involve a fair amount of work & time

AT LEAST 48 hours!

All listed authors must sign off on final document

Authors should take it seriously - review the entire document, not just the diffs.

Your last chance to avoid enrollment in the Errata Hall of Infamy!

Page 33
31 Jul 05 RFC Editor 33
General RFC Policies
∎ Immutability (but we get pretty close to the wire��) ∎ Not all RFC��s are standards ∎ All RFCs in in English
∎ RFC2026 allows translations ∎ British English is allowed in principle, but��
∎ Consistent Publication Format
∎ ASCII (also .txt.pdf for Windows victims) ∎ Also .ps or .pdf (special process for handling)

Page 34
31 Jul 05 RFC Editor 34
RFC Formatting Rules
∎ ASCII, 72 char/line. ∎ 58 lines per page, followed by FF (^L). ∎ No overstriking or underlining. ∎ No ��filling�� or (added) hyphenation across a line. ∎ <.><sp><sp> between sentences. ∎ No footnotes.

Page 35
31 Jul 05 RFC Editor 35
Parsing an RFC
∎ Header ∎ Title ∎ Header boilerplate (Short copyright, Status of Memo) ∎ IESG Note (when requested by IESG) ∎ Abstract ∎ Table of Contents (not req��d for short docs) ∎ Body ∎ Authors�� Addresses ∎ IPR boilerplate
∎ See RFC 3667/BCP 78, RFC 3668/BCP 79.

Page 36
31 Jul 05 RFC Editor 36
RFC Header
Network Working Group
T. Berners-Lee
Request for Comments: 3986
STD: 66
R. Fielding
Updates: 1738
Day Software
Obsoletes: 2732, 2396, 1808
L. Masinter
Category: Standards Track
Adobe Systems
January 2005
∎ STD number: labels a standard (as opposed to a
∎ One STD may include a set of related RFCs. ∎ An STD number will be re-assigned to replacement RFC(s) ∎ IETF considering elaboration of STD idea into an ��Internet
Standards Document (ISD)��
∎ Updates, Obsoletes: relation to earlier RFCs..

Page 37
31 Jul 05 RFC Editor 37
RFC Header: another example
Network Working Group
T. Berners-Lee
Request for Comments: 2396
Updates: 1808, 1738
R. Fielding
Category: Standards Track
U. C. Irvine L. Masinter Xerox Corporation August 1998
RFC2396 T. Berners-Lee, R. Fielding, L. Masinter August 1998 ASCII Obsoleted by RFC3986, Updates RFC1808, RFC1738, Updated by
Corresponding RFC Index entry (search on ��2396��) Note fields that were not known when RFC was published

Page 38
31 Jul 05 RFC Editor 38
More First-Page Stuff
Uniform Resource Identifier (URI): Generic Syntax
Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2005).

Page 39
31 Jul 05 RFC Editor 39
Authors in Header
∎ Limited to lead authors, document editors. ∎ There must be very good reason to list more than 5. ∎ All authors in header are responsible for ��48 hour�� review. ∎ Authors section should provide unambiguous contact
∎ Other names can be included in Contributors and/or
Acknowledgments sections.

Page 40
31 Jul 05 RFC Editor 40
∎ Titles
∎ Should be thoughtfully chosen ∎ No unexpanded abbreviations - except for very well known
∎ We like short, snappy titles, but sometimes��
∎ ��An alternative to XML Configuration Access Protocol
(XCAP) for manipulating resource lists and authorization lists, Using HTTP extensions for Distributed Authoring and Versioning (DAV)��*

(*So far, only an Internet Draft)
∎ Note the ambiguity, BTW

Page 41
31 Jul 05 RFC Editor 41
∎ DID they mean:
∎ ��Using HTTP extensions for Distributed
Authoring and Versioning (DAV)�� in place of XML Configuration Access Protocol (XCAP)��

Page 42
31 Jul 05 RFC Editor 42
∎ Abstracts
∎ Carefully written for clarity (HARD to write!) ∎ No unexpanded abbreviations (again, except well-known) ∎ No citations ∎ Less than 20 lines! Shorter is good. ∎ Not a substitute for the Introduction; redundancy is OK. ∎ I dislike abstracts that bury ��This document���� 10 lines
down, or omit it entirely!

Page 43
31 Jul 05 RFC Editor 43
Body of RFC
∎ First section should generally be ��1. Introduction��. ∎ Following special sections may appear:
∎ Contributions, Acknowledgments ∎ Internationalization Considerations

When needed -- see Sect 6, RFC 2277/BCP 18.
∎ References
∎ Sections that MUST appear:
∎ Security Considerations ∎ IANA Considerations

Page 44
31 Jul 05 RFC Editor 44
∎ Normative vs. Informative
∎ Normative refs in stds-track documents can hold up pub. ∎ [Normative gets over-used]
∎ Recommend against numeric citations "[37]". ∎ Citations and references must match. ∎ Handy file of RFC reference text:
∎ ftp://ftp.rfc-editor.org/in-notes/rfc-ref.txt

Page 45
31 Jul 05 RFC Editor 45
Copyrights and Patents
∎ Copyright Issues
∎ Specified in RFC 3977/BCP 77 ��IETF Rights in
∎ Independent submissions: generally follows IETF rules ∎ Differences should be of interest only to lawyers.
∎ Patent (��IPR��) issues
∎ RFC boilerplate specified in RFC 3978/BCP 78
��Intellectual Property Rights in IETF Technology��

Page 46
31 Jul 05 RFC Editor 46
Security Considerations
∎ Security Considerations section required in every
∎ IESG is (rightfully!) suspicious of ��There are no
security considerations in this document.��
∎ There are security considerations in nearly everything that
we do.
∎ The IESG asks for in-depth, meaningful SC sections!
∎ See: RFC 3552: ��Guidelines for Writing RFC Text on
Security Considerations��

Page 47
31 Jul 05 RFC Editor 47
IANA Considerations
∎ Primary input to IANA ∎ Defines:
∎ Individual code points, in one place ∎ New registries (number spaces), with instructions on future
assignment rules.
∎ Section is required in draft, but ��No IANA
Considerations�� section will be removed by RFC Editor.
∎ See: RFC 2434, ��Guidelines for Writing an IANA Considerations
Section in RFCs��

Page 48
31 Jul 05 RFC Editor 48
How to Write an RFC
∎ Some editorial guidelines ∎ Improving your writing ∎ Tools ∎ MIBs and formal languages

Page 49
31 Jul 05 RFC Editor 49
Writing an RFC
∎ Primary goal: clear, unambiguous technical
∎ Some preference for American English style
∎ The RFC Editor staff generally follows two sources
for style advice:
∎ Strunk & White (4th Edition, 2000) ∎ "A Pocket Style Manual" by Diana Hacker (4th Ed., 2004).
∎ In any case, internally consistent usage is required.

Page 50
31 Jul 05 RFC Editor 50
Writing RFCs
∎ Simple fact: writing clear, unambiguous technical
prose is very HARD !!
∎ Reread RFC 793 for inspiration and example.
∎ Not literary English, but comprehensibility would
be nice!
∎ Avoid ambiguity ∎ Use consistent terminology and notation ∎ Define each term and abbreviation at first use. ∎ Expand every abbreviation at first use.

Page 51
31 Jul 05 RFC Editor 51
Writing Hints
∎ Simple declarative sentences are good.
∎ Flowery, literary language is not good. ∎ Say enough, but not more than enough
∎ Avoid long, involuted sentences. You are not
James Joyce.
∎ Use ��;�� | ��, and�� | ��, or�� sparingly to glue successive
sentences together.
∎ Make parallel clauses parallel in syntax.
Bad: ���� whether the name should be of fixed length or
whether it is variable length��.

Page 52
31 Jul 05 RFC Editor 52
A Few Common Errors
∎ Some Protocol Engineers over-capitalize Nouns. ∎ Keep your sentences short and direct.
∎ Don��t make simple things complex
∎ ��which��s that should be ��that��s.
∎ ��Which�� is used parenthetically and follows a comma. ∎ ��The interface which the users sees is too complex.��
that /
∎ Or better: ��The user interface is too complex.��

Page 53
31 Jul 05 RFC Editor 53
RFC Editor conventions
∎ A comma before the last item of a series:
∎ ��TCP service is reliable, ordered, and full-duplex�� ∎ Avoids ambiguities, clearly shows parallelism.
∎ Punctuation outside quote marks:
��This is a sentence��{.|?|!}
∎ To avoid computer language ambiguities.

Page 54
31 Jul 05 RFC Editor 54
Lean and Mean
∎ You often improve your writing, by simply crossing
out extraneous extra words.
∎ Look at each sentence and ask yourself,
��Do I need every word to make my meaning clear and unambiguous?��
∎ English professors call it the ��Lard Factor�� (LF) [Lanham79] ∎ ��If you��ve not paid attention to your own writing before,
think of a LF of 1/3 to ½ as normal and don��t stop revising until you��ve removed it.�� [Lanham79]

[Lanham79] Richard Lanham, ��Revising Prose��, Scribner��s, New York, 1979

Page 55
31 Jul 05 RFC Editor 55
A Real Example
∎ "When the nature of a name is decided one must
decide whether the name should be of fixed length or whether it is variable length." (25 words)
∎ A. ��One must decide whether the length of a name should
be fixed or variable.�� (14 words, LF = .44)
∎ B. ��We may choose fixed or variable length for a particular
class of name.�� (13 words)
∎ C. ��A name may have fixed or variable length.��
(7 words, LF = .72)

Page 56
31 Jul 05 RFC Editor 56
Another Real Example
∎ "One way to avoid a new administrative overhead
would be for individuals to be able to generate statistically unique names." (20)
∎ A. ��We can avoid new administrative overhead by allowing
individuals to generate statistically unique names.�� (14, LF = .30)
∎ B. ��Allowing individuals to generate statistically unique
names will avoid new administrative overhead.�� (12, LF = .40)

Page 57
31 Jul 05 RFC Editor 57
∎ How about:
��New administrative overhead can be avoided by allowing individuals to generate statistically-unique names.��
∎ Compare to:
��The nail has been hit on the head by you!��
∎ Passive voice: generally a bad idea��

Page 58
31 Jul 05 RFC Editor 58
Another (reality-based) Example
∎ ��This is the kind of situation in which the receiver
is the acknowledger and the sender gets the acknowedgments.�� (19)
∎ ��An acknowledgment action is taking place from the
receiver and the sender.�� (11, LF=.42)
∎ ��The receiver returns acknowledgments to the sender.��
(7, LF=.63)

Page 59
31 Jul 05 RFC Editor 59
Another Real Example
∎ ��Also outside the scope are all aspects of network
security which are independent of whether a network is a PPVPN network or a private network (for example, attacks from the Internet to a web- server inside a given PPVPN will not be considered here, unless the way the PPVPN network is provisioned could make a difference to the security of this server).��
∎ Two sentences!! ∎ ��make a difference to�� -> ��affect��

Page 60
31 Jul 05 RFC Editor 60
Seeking Clarity, Resolving Ambiguity
∎ ��With appropriate consideration in router design,
in the event of failure of a BGP peer to provide the equivalent filtering, the risk of compromise can be limited to the peering session on which filtering is not performed by the peer or the interface or line card on which the peering is supported.��
∎ ��Appropriate router design can limit the risk of
compromise when a BGP peer fails to provide adequate filtering. The risk can be limited to the peering session on which filtering is not performed by the peer, or to the interface or line card on which the peering is supported.�� [??]

Page 61
31 Jul 05 RFC Editor 61
Removing ambiguity
∎ ��Consequently, BGP security is secondarily
dependent on the security of the protocols by which the platform is operated, managed and configured that might signal this event.��
∎ ��Consequently, BGP security is secondarily dependent
on the security of the platform��s operation, management, and configuration protocols that might signal this event��, OR
∎ ��Consequently, BGP security is secondarily dependent
on the security of the operation, management, and configuration protocols of the platform that might signal this event�� ??

Page 62
31 Jul 05 RFC Editor 62

Page 63
31 Jul 05 RFC Editor 63
Format for Readabilty
∎ Careful use of indentation and line spacing can
greatly improveme readability.
∎ Goes a long way to compensate for single font. ∎ Bullets often help.
∎ High density on the page may be the enemy of
clarity and readability

Page 64
31 Jul 05 RFC Editor 64
Hard to read
3.1 RSVP Message Formats 3.1.1 Common Header The fields in the common header are as follows: Flags: 4 bits 0x01-0x08: Reserved No flag bits are defined yet. Send_TTL: 8 bits The IP TTL value with which the message is sent. See Section 3.8.

Page 65
31 Jul 05 RFC Editor 65
Formatted for Easier Reading
3.1 Message Formats 3.1.1 Common Header The fields in the common header are as follows: Flags: 4 bits 0x01-0x08: Reserved No flag bits are defined yet. Send_TTL: 8 bits The IP TTL value with which the message is sent. See Section 3.8.

Page 66
31 Jul 05 RFC Editor 66
Preserving the Meaning
∎ A comment that does not faze us:
��How dare you change my perfect prose����?
∎ Sorry�� we are just doing our job. See earlier.
∎ A comment that concerns us very much:
��You have changed the meaning of what I wrote��.
∎ Often, because we misunderstood what you meant. ∎ That implies that your prose is ambiguous. ∎ You should recast the sentence/paragraph to make it
clear and unambiguous, so even the dumb RFC Editor cannot mistake the meaning. ;-)

Page 67
31 Jul 05 RFC Editor 67
Internet Drafts
∎ A well-formed RFC starts with a well-formed I-D ∎ Surviving IESG review:
∎ http://www.ietf.org/ID-Checklist.html ∎ http://www.ietf.org/ietf/1id-guidelines.txt

Page 68
31 Jul 05 RFC Editor 68
Text Formatting Tools
∎ Author tools: www.rfc-editor.org/formatting.html
∎ xml2rfc ∎ nroff ∎ Microsoft word templates ∎ LaTeX
∎ RFC Editor does final RFC formatting using venerable
Unix tool nroff –ms.

Page 69
31 Jul 05 RFC Editor 69
∎ Read RFC2629.txt - Marshall Rose
∎ Writing I-Ds and RFCs using XML ∎ Explains use of DTD for RFC production
∎ Engine to convert .xml to .txt or to .nroff
available online at: http://xml.resource.org/
∎ If you use xml2rfc, give the .xml file to the RFC Editor! It
saves us doing the markup on your document.
∎ Xml2rfc resources at: http://xml.resource.org/

Page 70
31 Jul 05 RFC Editor 70
nroff, groff
∎ Handy templates for authors using nroff:
∎ ftp.rfc-editor.org/in-notes/rfc-editor/2-nroff.template
∎ Published in 1991 - J. Postel ∎ Gives instructions on using macros for creating RFCs
∎ www.1-4-5.net/~dmm/generic_draft.tar.gz
∎ Updated nroff template maintained by David Meyer.
∎ If you use nroff –ms (without a private make file),
give the .nroff source to the RFC Editor.

Page 71
31 Jul 05 RFC Editor 71
MIB RFCs – Important special case
∎ MIB references
∎ O&M Web Site atwww.ops.ietf.org/ ∎ MIB doctors at www.ops.ietf.org/mib-doctors.html ∎ MIB Review: draft-ietf-ops-mib-review-guidelines
∎ Tools
∎ http://www.ops.ietf.org/mib-review-tools.html ∎ smilint at www.ibr.cs.tu-bs.de/projects/libsmi/ ∎ SMICng at www.snmpinfo.com/

Page 72
31 Jul 05 RFC Editor 72
Use of Formal Languages
∎ Formal languages and pseudo-code can be useful as an aid
in explanations, although English remains the primary method of describing protocols.
∎ Pseudo-code judged on the basis of clarity. ∎ Formal Languages (e.g., ABNF, XML, ASN.1 (MIBs))

Requires normative reference to language specification

RFC Editor will run verifier program.
∎ www.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txt ∎ ftp.rfc-editor.org/in-notes/rfc-editor/UsingPseudoCode.txt

Page 73
31 Jul 05 RFC Editor 73
Persistent Editorial Issues
∎ Normative references
∎ Practical effect: can hold up publication ∎ Some disagreement on what should be Normative
∎ MUST/MAY/SHOULD/�� applicability words
∎ Do they belong in Informative documents at all? ∎ Tend to overuse – makes it sound important. ∎ Worse, often inconsistent use
∎ URLs in RFCs
∎ Some are more stable than others��

Page 74
31 Jul 05 RFC Editor 74
Persistent Editorial Issues
∎ Author contact information
∎ Seems important, but hard to keep it current ∎ RFC Editor gets many queries from newbies. ∎ Ideal: maintain database of current email addresses;
daunting job.
∎ Update and Obsolete relationships
∎ Some disagreement on what they mean ∎ At best, only high-order bit of complex relationship ∎ RFC Editor supports ISD (Internet Standard Document)
[Newtrk] as more systematic and complete.

Page 75
31 Jul 05 RFC Editor 75
Persistent Issues
∎ ��What are the current Internet standards?��
∎ STD sub-series is supposed to define this. ∎ See STD 1: ��Official Internet Protocol Standards�� ∎ Latest: www.rfc-editor.org/rfcxx00.html
∎ In practice, reality is so complex that this is
probably not even a valid question.
∎ Again, ISDs would be better than STDs (but more work)
∎ What is meaning of Historic category?
∎ ��Really Bad��, or just ��well, not very current����?

Page 76
31 Jul 05 RFC Editor 76
Errata Page
∎ www.rfc-editor.org/errata.html
∎ A list of technical and editorial errors that have been
reported to the RFC Editor.
∎ Verified by the authors and/or the IESG. ∎ The RFC Editor search engine results contain hyperlinks to
errata, when present.

Page 77
31 Jul 05 RFC Editor 77
Authoritative references
∎ Overview of RFC publication:
∎ ��Instructions to Request for Comments (RFC)
Authors��. Draft-rfc-editor-rfc2223bis-08.txt aka ftp.rfc-

Page 78
31 Jul 05 78
Thank you
Questions? Comments? mailto:edu-discuss@ietf.org mailto:rfc-editor@rfc-editor.org

Set Home | Add to Favorites

All Rights Reserved Powered by Free Document Search and Download

Copyright © 2011
This site does not host pdf,doc,ppt,xls,rtf,txt files all document are the property of their respective owners. complaint#nuokui.com