| title | description | published | date | tags | editor | dateCreated |
|---|---|---|---|---|---|---|
References in RFCXML |
true |
2021-11-17 10:02:08 UTC |
markdown |
2021-11-04 23:45:18 UTC |
RFCXML uses references that are encoded in a format called BibXML, as defined in RFC 7991. To simplify the process of inserting references, the IETF maintains a set of online citation libraries as follows:
- For RFCs the official site is rfc-editor.org. The information page for each RFC has a link to the BibXML file.
- For RFCs, Internet-Drafts, and documents produced by the W3C, 3GPP, IANA and NIST, the new site is bib.ietf.org (at the time of writing, this site has only just gone live and some usability issues are still to be resolved). Many of these sets of references can be downloaded as a set for offline access.
Use an xi:include in the <references> section that points to a citation in the library as follows. The following creates a reference to an RFC:
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>For an Internet-Draft, the citation filename uses the draft string. Note there are two ways to create the URL. The first way, where the draft string is constructed as "I-D.<name without "draft-" or the version number>", will point to the most current version of the I-D, for example:
<xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-wgname-topic.xml"/>This is helpful if you do not want to track and update the reference entry each time the I-D is updated. However, if you want to point to a specific version of an I-D, the draft string should include both "draft-" and the version number. For example:
<xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-wgname-topic-17.xml"/>The following complete example is for an RFC (verbatim contents of https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml). Full references should only be used where an xi:include cannot be used, or where the authors wish to specify different BibXML from that supplied in the citation libraries:
<reference anchor="RFC2119" target="https://www.rfc-editor.org/info/rfc2119">
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials="S." surname="Bradner" fullname="S. Bradner">
<organization/>
</author>
<date year="1997" month="March"/>
<abstract>
<t>In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
</t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="2119"/>
<seriesInfo name="DOI" value="10.17487/RFC2119"/>
</reference>A bare minimum example is:
<reference anchor="min_ref">
<front>
<title>Minimal Reference</title>
<author initials="authInitials" surname="authSurName">
<organization/>
</author>
<date year="2006"/>
</front>
</reference>An example of a reference written by an organisation is:
<reference anchor="org_ref" target="https://www.example.com/">
<front>
<title>Organisational Reference</title>
<author>
<organization>Example Inc.</organization>
</author>
<date year="2001"/>
</front>
</reference>To cite a reference in your text, use an <xref> element where the value of its target attribute corresponds to the value of the anchor attribute of the reference element, e.g., <xref target="RFC2119" />. For references constructed with xi:include, the values of the target attributes are the following:
- For RFCs, "RFCNNNN" (4 digits, using leading zeros)
- For Internet-Drafts, "I-D.<name without "draft-" or the version number>", even if you specified a particular version with the
xi:include.
For example, [1] instead of [RFC2119]
In the <rfc> element, set the attribute symRefs to "false" for symbolic references. This makes reference tags be numeric, e.g., [1], instead of symbolic, e.g., [RFC2119].
For example, [IKEv2] instead of [RFC4306]
Use the <displayreference> element and set the to attribute to the nickname. Tip: place it before the first references element. For example:
<displayreference target="RFC7296" to="IKEv2"/>
<references>
[...]
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7296.xml"/>yields:
[IKEv2] Kaufman, C., Hoffman, P., Nir, Y., Eronen, P., and T.
Kivinen, "Internet Key Exchange Protocol Version 2
(IKEv2)", STD 79, RFC 7296, DOI 10.17487/RFC7296,
October 2014, <https://www.rfc-editor.org/info/rfc7296>.
In the <rfc> element, set the attribute sortRefs to "true". Note that sortRefs only has an effect if symRefs is "true".
The <eref> element for an external reference creates a link in the HTML output. For example:
<eref target="https://www.w3.org" />yields
<a href ="https://www.w3.org"/>and
<eref target="https://www.w3.org">W3C Home Page</eref>yields
<a href ="https://www.w3.org">W3C Home Page</a>Another option is using xref and creating a reference that uses the target attribute for the URL. For example:
<reference anchor="W3C" target="https://www.w3.org/">
<front>
<title>World Wide Web Consortium (W3C)</title>
<author/>
</front>
</reference>yields
[W3C] "World Wide Web Consortium (W3C)", <https://www.w3.org/>.
Use the <name> element (child of the <references> element) as follows:
<back>
<references>
<name>References</name>
<references>
<name>Normative References</name>
...
</references>
<references>
<name>Informative References</name>
...
</references>
</references>
</back>Use <referencegroup> with an xi:include for each RFC inside it:
<referencegroup anchor="STD78" target="https://www.rfc-editor.org/info/std78">
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5343.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5590.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5591.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6353.xml"/>
</referencegroup>which yields
[STD78] Schoenwaelder, J., "Simple Network Management Protocol
(SNMP) Context EngineID Discovery", STD 78, RFC 5343,
September 2008.
Harrington, D. and J. Schoenwaelder, "Transport Subsystem
for the Simple Network Management Protocol (SNMP)",
STD 78, RFC 5590, June 2009.
Harrington, D. and W. Hardaker, "Transport Security Model
for the Simple Network Management Protocol (SNMP)",
STD 78, RFC 5591, June 2009.
Hardaker, W., "Transport Layer Security (TLS) Transport
Model for the Simple Network Management Protocol (SNMP)",
STD 78, RFC 6353, July 2011.
<https://www.rfc-editor.org/info/std78>
Make sure the section you want to reference has an anchor attribute. For example:
<section anchor="s_using_lists">Then, refer to it with an <xref> element:
See <xref target="s_using_lists" />.which yields
See <a href="#s_using_lists">Section 4.</a>(where the number of that section is determined dynamically).
Use <xref> and set the sectionFormat attribute to various options.
To construct See Section 1.3 of [RFC7991], use "of" with the sectionFormat attribute:
See <xref target="RFC7991" sectionFormat="of" section="1.3" />To construct See [RFC7991], Section 1.3, use "comma" with the sectionFormat attribute:
See <xref target="RFC7991" sectionFormat="comma" section="1.3" />To construct See [RFC7991] (Section 1.3), use "parens" with the sectionFormat attribute:
See <xref target="RFC7991" sectionFormat="parens" section="1.3" />To construct See 1.3, use "bare" with the sectionFormat attribute:
See <xref target="RFC7991" sectionFormat="bare" section="1.3" />When sectionFormat is not set at all, the output is the same as "of".
For example, See Sections 3 and 4.
Use <xref> with the format attribute. For example, assuming the anchors for the relevant sections match the targets:
See Sections <xref target="s_using_refs" format="counter" /> and
<xref target="s_using_lists" format="counter" />.yields the output:
See Sections <a href="#s_using_refs">3</a> and <a href="#s_using_lists">4</a>.Note: The format attribute can have the value "title", which displays the title of the section. For example,
See Sections <xref target="s_using_refs" format="title" /> and
<xref target="s_using_lists" format="title" />.yields the output:
See <a href="#s_using_refs">Using References</a> and
<a href="#s_using_lists">Using Lists.</a>For example, 'see Sections 5 and 6 in RFC 3550'.
Use <xref> with sectionFormat="bare". For example:
See Sections <xref target="RFC3550" section="5" sectionFormat="bare" /> and
<xref target="RFC3550" section="6" sectionFormat="bare" /> in
<xref target="RFC3550"/>.yields the output:
See Sections <a href="https://www.rfc-editor.org/rfc/rfc3550#section-5">5</a>
and <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6">6</a> in
[<a href="#RFC3550">RFC3550</a>].Authors who often cite academic publications may find the bibtex2rfc tool, which converts BibTeX references into valid RFCXML references, helpful since most databases include bibliographic entries in BibTex format.