RSE Wiki Archive

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== xml2rfc examples =====

When considering "Is there a better way to do this?"

==== Summary ====
  - xref to a section in another RFC and the authors want to include the section title
  - xref with format="title" doesn't work as expected
  - <contact> inside <t> when providing more information than fullname 
  - 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).

Note: As discussed with Henrik Nov. 2019.

Example A (from rfc8658.notprepped.xml)

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

TEXT output:
<code>
described in Section 2 (IANA Considerations) of [RFC3575]
</code>

HTML output:
<html>
<p>defined in Section <a href="https://www.rfc-editor.org/rfc/rfc3575#section-2">2</a> (<a href="https://www.rfc-editor.org/rfc/rfc3575#section-2">IANA Considerations</a>) of [<a href="#RFC3575">RFC3575</a>]</p>
</html>

--------------
Example B (from rfc8731.notprepped.xml)

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

TEXT output:
<code>
defined in Section 7.1 (ECDH Message Numbers) of [RFC5656]
</code>

HTML output:
<html>
<p>defined in Section <a href="https://www.rfc-editor.org/rfc/rfc5656#section-7.1">7.1</a> (<a href="https://www.rfc-editor.org/rfc/rfc5656#section-7.1">ECDH Message Numbers</a>) of [<a href="#RFC5656">RFC5656</a>]</p>
</html>


==== 2) 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

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

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

Text output:
<code>
   This document obsoletes "["Dissemination of Flow Specification
   Rules"]" [RFC5575]
</code>

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: 
<code>
  This document obsoletes ["Dissemination of Flow Specification Rules"]
   [RFC5575]
</code>


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

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

a) name + org\\
XML: ''<t><contact fullname="Fabio Maino"/>, Cisco Systems, Inc.</t>''\\
(file: draft-ietf-lisp-gpe-19.xml - in the queue)\\
Original (in a list): ''   o  Fabio Maino, Cisco Systems, Inc.''

b) name + email\\
XML: ''<t><contact fullname="Ari Keränen"/> &lt;ari.keranen@ericsson.com&gt;</t>''\\
(file: rfc8790.notprepped.xml)\\
Original (in a registration template): ''Author:  Ari Keranen ari.keranen@ericsson.com''

c) name + email + org\\
XML: ''<t><contact fullname="Jiantao Fu"/> &lt;jianfu@cisco.com&gt; of Cisco Systems''\\
(file: rfc8698.notprepped.xml)\\
Original (in a paragraph in "Contributors"): ''<nowiki> Jiantao Fu <jianfu@cisco.com> of Cisco Systems</nowiki>''

Thinking aloud: ability to put the data in the contact element and have a decent rendering when in <t>.  (Currently, if we put additional data in the contact element when it's in <t>, the additional data doesn't appear in the output at all.)

==== 4) 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: published as rfc8940.xml (draft-ietf-emu-eap-session-id-07)
RSE Wiki Archive

User Tools

Site Tools

Page Tools
