Network Working Group (trad.) B. Carpenter Internet-Draft Univ. of Auckland Intended status: Informational C. Partridge Expires: August 26, 2011 BBN February 22, 2011 Recommendations of a committee on RFC citation issues draft-carpenter-rfc-citation-recs-01 Abstract The Transitional RFC Editor set up a small committee in 2010 to look into several issues concerning citations of, and within, RFCs. This report summarizes the committee's recommendations. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. 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." This Internet-Draft will expire on August 26, 2011. Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://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. Carpenter & Partridge Expires August 26, 2011 [Page 1] Internet-Draft RFC citation recommendations February 2011 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. International Standard Serial Number (ISSN) . . . . . . . . . 3 3. How documents in the RFC series should cite other RFCs . . . . 4 4. How documents in the RFC series should cite Internet-Drafts . 4 5. Citing RFCs from Other Documents . . . . . . . . . . . . . . . 6 5.1. General Advice on Citing RFCs . . . . . . . . . . . . . . 7 5.2. BibTeX Entries for RFCs . . . . . . . . . . . . . . . . . 7 6. Citing Internet-Drafts from Other Documents . . . . . . . . . 8 6.1. General Advice on Citing Internet-Drafts . . . . . . . . . 9 6.2. BibTeX Entries for Internet Drafts . . . . . . . . . . . . 10 7. Authors Initials . . . . . . . . . . . . . . . . . . . . . . . 10 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 11. Informative References . . . . . . . . . . . . . . . . . . . . 11 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 Carpenter & Partridge Expires August 26, 2011 [Page 2] Internet-Draft RFC citation recommendations February 2011 1. Introduction In July 2010, Glenn Kowack, the transitional RFC Editor (TRSE), set up a small committee to look into issues concerning citations of RFCs by other documents, and concerning how citations within RFCs, whether they be of RFCs, Internet-Drafts, or other documents. This document constitutes the committee's report and recommendations. The matters considered by the committee were: 1. Determine the right ISSN entry format for the RFC series and recommend how to ensure it is appropriately catalogued internationally. 2. Determine how documents in the RFC series should cite other RFCs. 3. Determine how documents in the RFC series should cite Internet- Drafts. 4. Recommend how RFCs should be cited using the ACM, IEEE and MLA reference formats. 5. Recommend how RFCs should be represented in BibTex. Over the course of its deliberations, the committee added an additional issue: 1. Whether to list all initials for authors. We now discuss these items in turn, with our conclusions and recommendations. 2. International Standard Serial Number (ISSN) An ISSN is an eight digit number that uniquely identifies a paper or electronic series publication such as a scientific journal; all issues of a given journal carry the same ISSN. It is used in both traditional and on-line library catalogues and the like, and is mentioned in some scholarly publications as part of a citation, although this is relatively rare. The RFC Series has ISSN 2070-1721. The ISSN does not convey any particular status; it is just intended as an aid for identification, cataloguing and searching. It applies retroactively to the entire RFC series. We make two recommendations: 1. The ISSN should be included when RFCs are cited, but only in cases where the same is done for other series publications. 2. The RFC Editor should take steps to ensure that the current ISSN registration held by issn.org and the appropriate entry at http://www.worldcat.org are up to date and accurate. Note: The current registration entry includes Carpenter & Partridge Expires August 26, 2011 [Page 3] Internet-Draft RFC citation recommendations February 2011 Publisher Marina del Rey, CA : IETF Trust Issuing body (as on the piece) IETF Trust Issuing body (as on the piece) Internet Engineering Task Force Issuing body (as on the piece) IETF The fact that the IETF Trust holds copyright does not make it the publisher. We RECOMMEND that both the publisher and the issuing body should be shown as "RFC Editor". This is much less prone to error than showing the various RFC streams as the issuing body. 3. How documents in the RFC series should cite other RFCs We have seen no convincing arguments for changing the current style and format, illustrated here [RFC2629] and in the References section below. An alternative style used in some RFCs is a numeric label such as [1] instead of a symbolic label. We consider this acceptable for RFCs containing many references where the symbolic style would be visually confusing. 4. How documents in the RFC series should cite Internet-Drafts The committee observed that Internet-Drafts are now widely cited. The reasons vary from establishing when an idea was developed (e.g. for patent purposes), to documenting design paths not followed, or simply giving credit for an idea where credit is due. Furthermore, for some of these purposes, the particular instantiation of the Internet-Draft matters as different drafts contain different information. There are multiple RFC publication streams.[RFC 4844] Different RFC publication streams might have different policies and practices with respect to an RFC citing an Internet-Draft.[RFC 4844] This document is merely the report of an ad-hoc committee to the RFC Editor. As such, this document does not create or modify any stream-specific policies or practices about whether or when an RFC might cite an Internet-Draft. Authors and editors of documents intended for RFC publication should consult stream-specific authorities to learn the policies and practices applicable to the various document streams. Carpenter & Partridge Expires August 26, 2011 [Page 4] Internet-Draft RFC citation recommendations February 2011 Some RFC publication streams at present do permit some citations of Internet-Drafts under some circumstances. So this committee could not ignore the question of how an RFC should cite an Internet-Draft. This committee focused purely on the practical issues of how an RFC citation of an Internet-Draft should be formatted. In this light, the committee RECOMMENDS that, except in standards track documents, the RFC Editor permit the citation of Internet- Drafts in RFCs. For the reasons discussed below, we also RECOMMEND updating the current practices for citing Internet-Drafts. Current practice is based on a strict interpretation of [RFC2026]: An Internet-Draft is NOT a means of "publishing" a specification; specifications are published through the RFC mechanism described in the previous section. Internet-Drafts have no formal status, and are subject to change or removal at any time. ******************************************************** * * * Under no circumstances should an Internet-Draft * * be referenced by any paper, report, or Request- * * for-Proposal, nor should a vendor claim compliance * * with an Internet-Draft. * * * ******************************************************** Note: It is acceptable to reference a standards-track specification that may reasonably be expected to be published as an RFC using the phrase "Work in Progress" without referencing an Internet-Draft. Thus, a recent citation today reads: [MIF-PRACTICE] Wasserman, M. and P. Seite, "Current Practices for Multiple Interface Hosts", Work in Progress, August 2010. Such a citation raises several possible problems: 1. It does not suffice for a reader who wishes to locate a copy, because it does not include the relevant file name. If the user finds a document with the same title, there is no certainty that it is the version cited. Carpenter & Partridge Expires August 26, 2011 [Page 5] Internet-Draft RFC citation recommendations February 2011 2. Furthermore, citing only the month of publication does not identify the version, if the document has been frequently updated. Indeed even citing the exact day of publication is insufficient; Internet-Drafts are sometimes updated more than once a day. 3. In some circumstances, an RFC might need to cite more than one version of the same draft (for example, when comparing alternative proposed solutions). This compunds the previous issue. 4. The phrase "Work in Progress" may be misleading or simply incorrect when referring to an older draft that has in fact been abandoned by its authors. Our discussions did not lead to a simple solution to these problems. We RECOMMEND that 1. The RFC Editor should include the exact publication date in the citation of an Internet-Draft. 2. Authors should be allowed to cite several versions of the same draft. 3. The RFC Editor is encouraged include the full Internet-Draft file name in citations. 4. A citation of an Internet-Draft should use the phrase "Working Draft" rather than "Work in Progress" whenever appropriate. (Stream-specific policies and practices might prohibit this practice within certain RFC document streams.) 5. Citing RFCs from Other Documents We believe that RFCs should be treated as scholarly publications for citation purposes [CCR]. Clearly, the exact format depends on the citation style adopted by a particular publisher. The Institute for Electrical and Electronics Engineers (IEEE) and the Association for Computing Machinery (ACM) are professional societies. Both publish a number of journals and conference proceedings in which RFCs are cited. The Modern Library Association (MLA) standards are widely used for doctoral dissertations in the United States. The committee discovered that while IEEE and ACM have canonical formats for citations, it turns out that their conferences and journals routinely are allowed to adopt different formats and do so. What does seem to be common is that virtually every journal and conference and dissertation preparation package knows how to translate a BIBTEX reference into the conference's or journal's preferred form. Accordingly, rather than worry about each citation format Carpenter & Partridge Expires August 26, 2011 [Page 6] Internet-Draft RFC citation recommendations February 2011 individually, the committee chose to focus on getting the BIBTEX representation discussed in the next section in a form that would lead to clear, consistent, and effective citations. 5.1. General Advice on Citing RFCs The committee's BibTeX discussions were guided by the following decisions regarding how we felt RFCs should be cited. 1. The publisher, institution, or organization is identified as the "RFC Editor" (not the IETF, the IRTF, the IETF Trust, the Internet Society, etc.). 2. The copyright holder is "The IETF Trust". 3. The ISSN is 2070-1721. 4. If a series name is required, it should be "Internet Requests for Comment". 5. The volume number is the RFC number itself, e.g. "RFC 2026". 6. The correct typography includes a blank space. Both "RFC2026" and "RFC-2026" are incorrect as a descriptive term. 7. The URL format is http://www.rfc-editor.org/rfc/rfc####.txt where #### is replaced with the four digit RFC number (for numbers below 1000, there is no leading 0). 8. Some RFCs are collective works attributed to editors, rather than authors. This should be indicated in the citation. 5.2. BibTeX Entries for RFCs At present, a very wide range of different BibTeX entry types are used (e.g. @ARTICLE, @MISC, @TECHREPORT) which often yields incomplete and inconsistent citations. Also, a wide range of values have been used for PUBLISHER or INSTITUTION over the years. We hope to reduce inconsistency, increase accuracy, and also improve clarity of RFC citations by specifying a standard BibTeX entry format for use in citing RFCs. All RFCs receive substantial review prior to publication. While RFCs published on different tracks have slight variances in the review process (e.g. IRTF track RFCs are reviewed by the IRSG before publication, while IETF track RFCs are reviewed by the IESG instead), all RFCs receive substantial technical review prior to publication. [RFC 5741][RFC 5742][RFC 5743] In most cases, an RFC has also had significant public review within the Internet engineering and research community prior to publication as an RFC. As such, all RFCs are reviewed publications; in many cases they are peer-reviewed [CCR]. We mention this here in part because some organisational technical reports, which might also be cited using the @TECHREPORT BibTeX entry type, are not normally peer-reviewed prior to publication as a Carpenter & Partridge Expires August 26, 2011 [Page 7] Internet-Draft RFC citation recommendations February 2011 technical report. We RECOMMEND that all authors citing RFCs from documents other than RFCs and Internet-Drafts use the @TECHREPORT{} entry type, with the fields and values illustrated in the example below. When an RFC includes the day of the month when it was published, it also is important to include the day in the BibTeX entry. Many RFCs list only month and year, as in the example entry below. We also RECOMMEND that the RFC Editor create and maintain a canonical BibTeX file at a stable public location on the web server "www.rfc- editor.org", so that authors using BibTeX can easily obtain a BibTeX file with all issued RFCs. @techreport{rfc1654, AUTHOR = "Yakov Rekhter and Tony Li", TITLE = "{A Border Gateway Protocol 4 (BGP-4)}", HOWPUBLISHED = {Internet Requests for Comments}, TYPE="{RFC}", NUMBER=1654, PAGES = {1-56}, YEAR = {1995}, MONTH = {July}, ISSN = {2070-1721}, PUBLISHER = "{RFC Editor}", INSTITUTION = "{RFC Editor}", URL={http://www.rfc-editor.org/rfc/rfc1654.txt} } 6. Citing Internet-Drafts from Other Documents Many documents written and published outside the RFC process cite Internet-Drafts, despite their ephemeral and unpublished nature. The question of whether a particular publisher or publication permits citation of Internet-Drafts is outside the scope of this committee report. The committee focused purely on developing guidance for formatting citation of Internet-Drafts by other documents. Unlike RFCs, Internet-Drafts have no formal status and are intended for short-term use, such as draft development. Each version of each Internet-Draft expires after 6 months. In many cases the draft is revised and a new version of that Internet-Draft then becomes valid. As working documents, the level to which an Internet-Draft has been reviewed varies widely. Internet-Drafts actively being worked on as official IAB, IESG, IETF WG, or IRTF RG drafts are often being Carpenter & Partridge Expires August 26, 2011 [Page 8] Internet-Draft RFC citation recommendations February 2011 carefully reviewed and edited. Other Internet-Drafts also may have been widely circulated for review and reflect careful editng. However, it is impossible to determine the level of review and editing simply by looking at the origin of an Internet-Draft. [RFC 2026] specifies that active IETF stream Internet-Drafts be cited as "Work in Progress". This has created some confusion, especially in the case where a draft being cited has both expired and also is not actively being worked on. We RECOMMEND that "Working Draft" be used for IETF stream Internet- Drafts that have expired and are no longer part of an active IETF initiative. A good sign of such cases is when a newer draft has been released or a draft has been expired for over a year. For all other publishing streams, we RECOMMEND that "Working Draft" be used to characterize all Internet-Drafts. As with RFCs, rather than worry about each citation format individually, the committee chose to focus on getting the BIBTEX representation in a form that will consistently lead to effective citations. 6.1. General Advice on Citing Internet-Drafts The committee's BibTeX discussions were guided by the following decisions regarding how we felt Internet-Drafts should be cited. 1. Internet-Drafts are not published documents, so there is no publisher. As such, don't include a publisher in the BibTeX entry or printed citation of an Internet-Draft. 2. At present, all Internet-Drafts, regardless of intended document track, are processed and made available by the IETF Secretariat. So the ORGANIZATION or INSTITUTION field should contain: "IETF Secretariat". 3. The copyright holder is: "The IETF Trust". 4. There is no ISSN, because an Internet-Draft has not been published. 5. If a series name is required, it should be: "Internet Drafts" 6. The number field should be the complete filename of the Internet- Draft being cited. Normally this SHOULD be the text version, as that is the canonical version. In special situations, for example where complex equations or drawings are included, an alternative version (e.g. HTML, PDF) MAY be referenced. 7. While many modern Internet-Drafts are available from an IETF Secretariat tools web site even after expiration, normally the URL for the Internet Draft SHOULD be omitted from the BibTeX entry. In special situations, for example an older Internet- Draft whose online location is obscure, a URL MAY be included. Carpenter & Partridge Expires August 26, 2011 [Page 9] Internet-Draft RFC citation recommendations February 2011 8. Some Internet-Drafts are collective works attributed to editors, rather than authors. This should be indicated in the citation. 9. For IETF stream drafts, HOWPUBLISHED MUST be "Work in Progress". For other Internet-Drafts, the HOWPUBLISHED field SHOULD read "Working Draft" instead. 6.2. BibTeX Entries for Internet Drafts At present, a very wide range of different BibTeX entry types are used (e.g. @ARTICLE, @MISC, @TECHREPORT) which often yields incomplete and inconsistent citations. Also, a wide range of values have been used for PUBLISHER or INSTITUTION over the years. We hope to reduce inconsistency, increase accuracy, and also improve clarity of Internet-Draft citations by specifying a standard BibTeX entry format for use in citing them. We RECOMMEND that all authors citing Internet-Drafts from documents other than RFCs and Internet-Drafts use the @TECHREPORT{} entry type, with the fields and values illustrated in the example below. It is important to include the full date and full Internet-Draft filename within the BibTeX entry in order to make the precise intended document and document version clear. @TECHREPORT{draft-ipng-gseaddr-00.txt, AUTHOR="M. O'Dell", TITLE="{GSE: An Alternate Addressing Architecture for IPv6}", HOWPUBLISHED="{Working Draft}", TYPE="{Internet-Draft}", NUMBER="draft-ipng-gseaddr-00.txt", INSTITUTION="{IETF Secretariat}", DAY=24, MONTH=Feb, YEAR=1997 } 7. Authors Initials While looking at how RFCs and Internet-Drafts are cited, the committee noted that many authors citing RFCs or Internet-Drafts composed the citation only from either the first page of the cited document or only from the RFC Index (e.g. rfc-index.txt). The committee observed that the practice of limiting ourselves to a single author initial in RFCs and Internet-Drafts thereby occasionally leads to uncertainty about who authored or edited the document being cited. The solution is clear but inevitably requires a change to RFC and Carpenter & Partridge Expires August 26, 2011 [Page 10] Internet-Draft RFC citation recommendations February 2011 Internet-Draft document formats. The committee RECOMMENDS that ALL of an author's initials be included both when the author's name is listed on the front page of the RFC or Internet-Draft, at the foot of each page and in author contact information. We further RECOMMEND that this practice carry over into citations and that all author initials be included in any citation. 8. Security Considerations Accurate and up to date references are important to ensure that all those involved in specifying, implementing, operating, and using Internet protocols apply the best possible security measures. 9. IANA Considerations This document makes no request of the IANA. 10. Acknowledgements The committee members were Ran Atkinson, Brian Carpenter, Dave Crocker, Paul Hoffman, Craig Partridge, Julian Reschke and Peter Saint-Andre. The committee was convened by Craig Partridge, occasionally assisted by Brian Carpenter. Useful comments and contributions were made by .... This document was produced using the xml2rfc tool [RFC2629]. 11. Informative References [CCR] Carpenter, B. and C. Partridge, "Internet Requests for Comments (RFCs) as Scholarly Publications", ACM SIGCOMM CCR 40 (1) 31-33, 2010. [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. [RFC4844] Daigle, L. and Internet Architecture Board, "The RFC Series and RFC Editor", RFC 4844, July 2007. [RFC5741] Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers, Carpenter & Partridge Expires August 26, 2011 [Page 11] Internet-Draft RFC citation recommendations February 2011 and Boilerplates", RFC 5741, December 2009. [RFC5742] Alvestrand, H. and R. Housley, "IESG Procedures for Handling of Independent and IRTF Stream Submissions", BCP 92, RFC 5742, December 2009. [RFC5743] Falk, A., "Definition of an Internet Research Task Force (IRTF) Document Stream", RFC 5743, December 2009. Authors' Addresses Brian Carpenter Department of Computer Science University of Auckland PB 92019 Auckland, 1142 New Zealand Email: brian.e.carpenter@gmail.com Craig Partridge Raytheon BBN Technologies 10 Moulton St Cambridge, MA 02138 USA Email: craig@aland.bbn.com Carpenter & Partridge Expires August 26, 2011 [Page 12]