User Tools

Site Tools


guidance_constructing_refs

Guidance for constructing references in v3 XML

RFC references (bibxml aka bibxml-rfcs)

Notes:

  • <reference> element:
    • The anchor attribute (which is used to create the citation tag) of the <reference> element should use the following default in bibxml-service entries:
      • anchor=“RFCNNNN”
    • The target attribute:
      • Should use the following URL construction:
        • RFC: https://www.rfc-editor.org/info/rfcNNNN
  • <title> element:
    • ASCII equivalents (e.g., double quotes, hyphens) are to be used for punctuation (e.g., to replace smart quotes and em dashes).
  • <author> element:
    • non-ASCII in <author> attributes is okay.
    • Note that RFC entries do not have <organization> elements because the API (rfc-index.xml) does not provide that data.
  • <date> element:
    • RFCs (except for April 1 RFCs) have month and year attributes only.
    • April 1 RFCs must have day=“1”, month=“April”, and year attributes specified.
  • <seriesInfo> element:
    • Although <seriesInfo> can now go into the <front> element, the RPC follows received guidance to keep it out of <front>.
    • RFCs have two <seriesInfo> elements:
      • <seriesInfo name=“RFC” value=“NNNN”/>
      • <seriesInfo name=“DOI” value=“10.17487/RFCNNNN”/>
  • <format> element:
    • Although originally provided by tools.ietf.org bibxml, this element should not be used. See the discussion.
  • Numbering:
    • RFCs have padding of leading zeros for numbers used in the value attribute of DOI <seriesInfo>, but not for other seriesInfo names. For example:
      • <seriesInfo name=“DOI” value=“10.17487/RFC0001”/>
      • <seriesInfo name=“RFC” value=“1”/>

v3 XML:

<reference anchor="RFC3080" target="https://www.rfc-editor.org/info/rfc3080">
  <front>
    <title>The Blocks Extensible Exchange Protocol Core</title>
    <author fullname="M. Rose" initials="M." surname="Rose"/>
    <date month="March" year="2001"/>
    <abstract>
      <t>
This memo describes a generic application protocol kernel for connection-oriented, asynchronous interactions called the BEEP (Blocks Extensible Exchange Protocol) core. [STANDARDS-TRACK]
      </t>
    </abstract>
  </front>
  <seriesInfo name="RFC" value="3080"/>
  <seriesInfo name="DOI" value="10.17487/RFC3080"/>
</reference>

Expected Output: See the example at https://www.rfc-editor.org/styleguide/part2/#ref_rfcs

   [RFC3080]  Rose, M., “The Blocks Extensible Exchange Protocol Core”, 
              RFC 3080, DOI 10.17487/RFC3080, March 2001, 
              <https://www.rfc-editor.org/info/rfc3080>.

I-D references (bibxml3 aka bibxml-ids)

Notes:

  • <reference> element:
    • The anchor attribute (which is used to create the citation tag) of the <reference> element should use the following default in bibxml-service entries:
      • anchor=“I-D.draftname” (draftname should not contain “draft-” nor “-NN”. For example, “I-D.ietf-jmap-blob” or “I-D.flanagan-7322bis”)
    • The target attribute:
      • Should use the following URL constructions:
        • I-D: https://datatracker.ietf.org/doc/html/draftname-NN
  • <title> element:
    • ASCII equivalents (e.g., double quotes, hyphens) are to be used for punctuation (e.g., to replace smart quotes and em dashes).
  • <author> element:
    • non-ASCII in <author> attributes is okay.
    • datatracker provides <organization> elements.
  • <date> element:
    • I-Ds have month, day, and year attributes.
  • <seriesInfo> element:
    • Although <seriesInfo> can now go into the <front> element, the RPC follows received guidance to keep it out of <front>.
    • I-Ds have one <seriesInfo> element, where draftname includes “draft-”:
      • <seriesInfo name=“Internet-Draft” value=“draftname-NN”/>
  • <format> element:
    • Although originally provided by tools.ietf.org bibxml, this element should not be used. See the discussion.
  • Numbering:
    • I-Ds have padding of a leading zero for draft version (e.g., “-01”)

v3 XML:

<reference anchor="I-D.ietf-httpbis-alias-proxy-status" target="https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-alias-proxy-status-01">
  <front>
    <title>HTTP Proxy-Status Parameter for Next-Hop Aliases</title>
    <author initials="T." surname="Pauly" fullname="Tommy Pauly">
      <organization>Apple, Inc.</organization>
    </author>
    <date month="January" day="18" year="2023"/>
    <abstract>
      <t>
This document defines an HTTP Proxy-Status Parameter that contains a list of aliases and canonical names received over DNS when establishing a connection to the next hop.
      </t>
    </abstract>
  </front>
  <seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-alias-proxy-status-01"/>
</reference>

Expected Output: See the example at https://www.rfc-editor.org/styleguide/part2/#ref_ids.

   [I-D.ietf-httpbis-alias-proxy-status]
              Pauly, T., "HTTP Proxy-Status Parameter for Next-Hop
              Aliases", Work in Progress, Internet-Draft, draft-ietf-
              httpbis-alias-proxy-status-01, 18 January 2023,
              <https://www.ietf.org/archive/id/draft-ietf-httpbis-alias-
              proxy-status-01.txt>.

Subseries References (bibxml9 aka bibxml-rfcsubseries)

Notes:

  • <referencegroup> element:
    • The anchor attribute (which is used to create the citation tag) of the <referencegroup> element should use the following default constructions in bibxml-service entries:
      • anchor=“BCPNNN”
      • anchor=“STDNNN”
      • anchor=“FYINNN”
    • The target attribute:
      • Should use one of the following URL constructions:
        • BCP: https://www.rfc-editor.org/info/bcpNNN
        • STD: https://www.rfc-editor.org/info/stdNNN
        • FYI: https://www.rfc-editor.org/info/stdNNN
  • <reference> element:
    • Used for each RFC within the subseries.
    • The anchor attribute:
      • anchor=“RFCNNNN”
    • The target attribute:
      • Should not be specified.
    • <title> element:
      • ASCII equivalents (e.g., double quotes, hyphens) are to be used for punctuation (e.g., to replace smart quotes and em dashes).
      • <author> element:
        • non-ASCII in <author> attributes is okay.
        • Note that RFC entries do not have <organization> elements because the API (rfc-index.xml) does not provide that data.
      • <date> element:
        • RFCs (except for April 1 RFCs) have month and year attributes only.
    • <seriesInfo> element:
      • Although <seriesInfo> can now go into the <front> element, the RPC follows received guidance to keep it out of <front>.
      • RFCs in an subseries have three <seriesInfo> elements:
        • <seriesInfo name=“STD” value=“NNN”/> (or name=“BCP” or name=“FYI”)
        • <seriesInfo name=“RFC” value=“NNNN”/>
        • <seriesInfo name=“DOI” value=“10.17487/RFCNNNN”/>
    • <format> element:
      • Although originally provided by tools.ietf.org bibxml, this element should not be used. See the discussion.
    • Numbering:
      • RFCs have padding of leading zeros for numbers used in the value attribute of DOI <seriesInfo>, but not for other seriesInfo names. For example:
        • <seriesInfo name=“DOI” value=“10.17487/RFC0001”/>
        • <seriesInfo name=“RFC” value=“1”/>
        • <seriesInfo name=“STD” value=“1”/>

v3 XML:

  <referencegroup anchor="BCP13" target="https://www.rfc-editor.org/info/bcp13">
    <reference anchor="RFC4289">
      <front>
        <title>
Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures
        </title>
        <author fullname="N. Freed" initials="N." surname="Freed"/>
        <author fullname="J. Klensin" initials="J." surname="Klensin"/>
        <date month="December" year="2005"/>
        <abstract>
          <t>
This document specifies IANA registration procedures for MIME external body access types and content-transfer-encodings. 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="13"/>
      <seriesInfo name="RFC" value="4289"/>
      <seriesInfo name="DOI" value="10.17487/RFC4289"/>
    </reference>
    <reference anchor="RFC6838">
      <front>
        <title>
Media Type Specifications and Registration Procedures
        </title>
        <author fullname="N. Freed" initials="N." surname="Freed"/>
        <author fullname="J. Klensin" initials="J." surname="Klensin"/>
        <author fullname="T. Hansen" initials="T." surname="Hansen"/>
        <date month="January" year="2013"/>
        <abstract>
          <t>
This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice.
          </t>
        </abstract>
      </front>
      <seriesInfo name="BCP" value="13"/>
      <seriesInfo name="RFC" value="6838"/>
      <seriesInfo name="DOI" value="10.17487/RFC6838"/>
    </reference>
  </referencegroup>

Expected output:

   [BCP13]    Freed, N. and J. Klensin, "Multipurpose Internet Mail
              Extensions (MIME) Part Four: Registration Procedures",
              BCP 13, RFC 4289, December 2005.

              Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13,
              RFC 6838, January 2013.

              <https://www.rfc-editor.org/info/bcp13>
guidance_constructing_refs.txt · Last modified: 2023/03/07 13:00 by jmahoney