User Tools

Site Tools


xml2rfc_examples

This is an old revision of the document!


Table of Contents

xml2rfc examples

Summary

  1. xref to a section in another RFC and the authors want to include the section title
  2. xref to a section in another RFC when it's not desired to have the RFC number immediately afterwards.
  3. xref with format=“title” doesn't work as expected
  4. <contact> inside <t> when providing more information than fullname
  5. blank line between <dt> and <dd>

Details

1) xref to a section in another RFC and the authors want to include the section title

It requires 2 xrefs to get the desired output (using sectionFormat=“bare” for the first one).

Example from file rfc8711.notprepped.xml

Section <xref target="I-D.haberman-iasa20dt-recs" section="3.2" sectionFormat="bare”/> 
(Lack of Resources) and              
Section <xref target="I-D.haberman-iasa20dt-recs" section="3.4" sectionFormat="bare"/>
(Funding/Operating Model Mismatch and Rising Costs) of 
<xref target="I-D.haberman-iasa20dt-recs" format="default”/>.

See 2 more examples below.

2) xref to a section in another RFC when it's not desired to have the RFC number immediately afterwards.

workaround: rephrase to avoid using sectionFormat=“bare”

[I will do more work here: to add example]

3) xref with format="title" doesn't work as expected

bc it includes square brackets around the title in the text file

Example from rfc8955.xml (draft-ietf-idr-rfc5575bis-27) in AUTH48

This document obsoletes "<xref target="RFC5575" format="title"/>" 
<xref target="RFC5575" format="default"/>

PDF and HTML are OK, but the text output is not correct

Text output:

   This document obsoletes "["Dissemination of Flow Specification
   Rules"]" [RFC5575] (see Appendix B for the differences).

Also: If we manually add quotes for the title to be quoted (as in the example above), the text rendering automatically puts quotes in - resulting in errored output (2 sets of quotes).

Without the added quotes, we get the following:

  This document obsoletes ["Dissemination of Flow Specification Rules"]
   [RFC5575] (see Appendix B for the differences).

[I will do more work here: put some files re: rfc8955.original.v2v3.xml]

4) use <contact> inside <t> when providing more information than fullname

The functionality exists when <contact> is outside <t> (e.g., a contributor listed in the style of an address block), but when the <contact> is in <t> in a list, it's not possible. So we end up putting data about the individual outside the <contact> element.

a) name + org
<t><contact fullname=“Fabio Maino”/>, Cisco Systems, Inc.</t>
(file: draft-ietf-lisp-gpe-19.xml - in the queue)

b) name + email
<t><contact fullname=“Ari Keränen”/> &lt;ari.keranen@ericsson.com&gt;</t>
(file: rfc8790.notprepped.xml)

c) name + email + org
<t><contact fullname=“Jiantao Fu”/> &lt;jianfu@cisco.com&gt; of Cisco Systems
(file: rfc8698.notprepped.xml)

5) get a <dl> with a blank line between <dt> and <dd>

Mail sent 2020-10-15 with details.

workaround: using <br/> (per reply from Henrik)

suggestion from Jean for dl's newline attribute: newline=“false|break|space”

file: rfc8940.xml (draft-ietf-emu-eap-session-id-07) in AUTH48 currently

More on #1

xref to published RFC with section number and section title

Note: As discussed with Henrik Nov. 2019.

Example 1 (from rfc8658.notprepped.xml)
XML:

described in Section <xref target="RFC3575" section="2" 
sectionFormat="bare">IANA Considerations</xref> of <xref target="RFC3575"/>

TEXT output:

described in Section 2 (IANA Considerations) of [RFC3575]

HTML output:

defined in Section 2 (IANA Considerations) of [RFC3575]

Example 2 (from rfc8731.notprepped.xml)
XML:

defined in Section <xref target="RFC5656" section="7.1" 
sectionFormat="bare">ECDH Message Numbers</xref> of <xref target="RFC5656"/>

TEXT output:

defined in Section 7.1 (ECDH Message Numbers) of [RFC5656]

HTML output:

defined in Section 7.1 (ECDH Message Numbers) of [RFC5656]

xml2rfc_examples.1603841591.txt.gz · Last modified: 2020/10/27 16:33 by arusso