Re: [TOOLS-DEVELOPMENT] Preview release of Text Submission Converter, id2xml

[Megan Ferguson <[e-mail]>]

Hi Henrik,

Some notes on our initial test pass.  Please let me know if you would like any further information on any of the points below.

Disclaimer: We understand that the editors will need to clean up the XML when it’s been converted from .txt to .xml.  Please note that we are reporting oddities without trying to figure out which ones could be fixed (i.e., automated).  

Thank you.

Megan

PIs, etc.
——

1) We were surprised to see symrefs set to no as most reference entries we see use the RFC number as citation tag.

2) We see the encoding as utf-8.  We were under the impression that ascii would be the default unless utf-8 characters were included in the file, which they were not in our test cases.

Author elements
————————

3) We see several differences in the use of the elements in the author’s postal address.

v2:
    <author fullname="Les Ginsberg" initials="L" surname="Ginsberg">
      <organization>Cisco Systems</organization>

      <address>
        <postal>
          <street>821 Alder Drive</street>
          <city>Milpitas</city>
          <code>95035</code>
          <region>CA</region>
          <country>USA</country>
        </postal>

        <email>[e-mail]</email>
      </address>
    </author>


id2xml:

    <author fullname="Les Ginsberg" surname="Ginsberg" initials="L. ">
      <organization>Cisco Systems</organization>
      <address>
        <postal>
          <street>821 Alder Drive</street>
          <street>Milpitas, CA  95035</street>
          <street>USA</street>
        </postal>
        <email>[e-mail]</email>
      </address>
    </author>


Artwork tags vs. lists 
———————
4) The following list was converted to a hanging list, which really changed the output.  
The author-submitted version had this list in artwork.


Original text:

   An MI-RTR MUST NOT support [RFC5120] multi-topology within a non-zero
   instance when any non-zero ITID is supported.  The following TLVs
   MUST NOT be sent in an LSP associated with a non-zero instance which
   supports a non-zero ITID and such an LSP MUST be ignored when
   received:

    TLV 222 - MT IS Neighbors
    TLV 235 - MT IP Reachability
    TLV 237 - MT IPv6 Reachability

id2xml text output:

   An MI-RTR MUST NOT support [RFC5120] multi-topology within a non-zero
   instance when any non-zero ITID is supported.  The following TLVs
   MUST NOT be sent in an LSP associated with a non-zero instance which
   supports a non-zero ITID and such an LSP MUST be ignored when
   received:

   TLV 222 - MT IS Neighbors

      TLV 235 - MT IP Reachability TLV 237 - MT IPv6 Reachability


In v2 (as submitted by authors):

      <figure>
        <artwork>
<![CDATA[ 

 TLV 222 - MT IS Neighbors
 TLV 235 - MT IP Reachability
 TLV 237 - MT IPv6 Reachability


]]></artwork>
      </figure>


In id2xml:

      <t>
        <list style="hanging"><t hangText="TLV 222 - MT IS Neighbors"/>
<t>    TLV 235 - MT IP Reachability
    TLV 237 - MT IPv6 Reachability</t></list>
      </t>

Another related example:

In the original text:

   Per [RFC6822], IANA has registered two EUI-48 multicast addresses
   from the IANA-managed EUI address space as specified in [RFC7042].
   The addresses are as follows:

      01-00-5E-90-00-02 AllL1MI-ISs
      01-00-5E-90-00-03 AllL2MI-ISs

   All references to [RFC6822] in the IS-IS TLV Codepoints registry
   should be replaced by references to this document.


In the id2xml text output:

   Per [RFC6822], IANA has registered two EUI-48 multicast addresses
   from the IANA-managed EUI address space as specified in [RFC7042].
   The addresses are as follows:

   01-00-5E-90-00-02 AllL1MI-ISs

      01-00-5E-90-00-03 AllL2MI-ISs

   All references to [RFC6822] in the IS-IS TLV Codepoints registry
   should be replaced by references to this document.


In v2 (as submitted by authors)

      <t><figure>
          <artwork>
<![CDATA[   01-00-5E-90-00-02 AllL1MI-ISs 

   01-00-5E-90-00-03 AllL2MI-ISs 

]]></artwork>
        </figure></t>



      <t><figure>
          <artwork><![CDATA[   01-00-5E-90-00-02 AllL1MI-ISs                             
   01-00-5E-90-00-03 AllL2MI-ISs                                                         
]]></artwork>
        </figure></t>


In id2xml:

      <t>
        <list style="hanging"><t hangText="01-00-5E-90-00-02 AllL1MI-ISs"/>
<t>      01-00-5E-90-00-03 AllL2MI-ISs</t></list>
      </t>

5) The text following this figure was originally included in an <artwork> tag and appeared as slightly indented in the text.

original text:

     Type:   7
     Length: 2 - 254
     Value:
                                            No. of octets
                 +-------------------------+
                 | IID (0 - 65535)         |     2
                 +-------------------------+
                 | Supported ITID          |     2
                 +-------------------------+
                 :                         :
                 +-------------------------+
                 | Supported ITID          |     2
                 +-------------------------+

     When the IID = 0, the list of supported ITIDs MUST NOT be present.

     An IID-TLV with IID = 0 MUST NOT appear in an SNP or LSP. When
     the TLV appears (with a non-zero IID) in an SNP or LSP, exactly
     one ITID MUST be present indicating the instance-specific topology
     with which the PDU is associated. If no ITIDs or multiple ITIDs are
     present or the IID is zero, then the PDU MUST be ignored.

     When the IID is non-zero and the TLV appears in an IIH, the set
     of ITIDs supported on the circuit over which the IIH is sent is
     included. There MUST be at least one ITID present.

     ITID #0 is reserved for a specific use case as described later
     in this document. ITID #0 MUST NOT be supported in combination
     with any non-zero ITID. If multiple ITIDs are advertised in
     an IIH and one of the ITIDs is #0 then the PDU MUST be ignored.

     Multiple IID-TLVs MAY appear in IIHs. If multiple IID-TLVs are
     present and the IID value in all IID-TLVs is not the same, then
     the PDU MUST be ignored.

   A single IID-TLV will support advertisement of up to 126 ITIDs.  If
   multiple IID-TLVs are present in an IIH PDU, the supported set of
   ITIDs is the union of all ITIDs present in all IID-TLVs.


id2xml text output:

     Type:   7
     Length: 2 - 254
     Value:
                                            No. of octets
                 +-------------------------+
                 | IID (0 - 65535)         |     2
                 +-------------------------+
                 | Supported ITID          |     2
                 +-------------------------+
                 :                         :
                 +-------------------------+
                 | Supported ITID          |     2
                 +-------------------------+

   When the IID = 0, the list of supported ITIDs MUST NOT be present.

   An IID-TLV with IID = 0 MUST NOT appear in an SNP or LSP.  When

      the TLV appears (with a non-zero IID) in an SNP or LSP, exactly
      one ITID MUST be present indicating the instance-specific topology
      with which the PDU is associated.  If no ITIDs or multiple ITIDs
      are present or the IID is zero, then the PDU MUST be ignored.

   When the IID is non-zero and the TLV appears in an IIH, the set

      of ITIDs supported on the circuit over which the IIH is sent is
      included.  There MUST be at least one ITID present.

   ITID #0 is reserved for a specific use case as described later

      in this document.  ITID #0 MUST NOT be supported in combination
      with any non-zero ITID.  If multiple ITIDs are advertised in an
      IIH and one of the ITIDs is #0 then the PDU MUST be ignored.

   Multiple IID-TLVs MAY appear in IIHs.  If multiple IID-TLVs are

      present and the IID value in all IID-TLVs is not the same, then
      the PDU MUST be ignored.

   A single IID-TLV will support advertisement of up to 126 ITIDs.  If
   multiple IID-TLVs are present in an IIH PDU, the supported set of
   ITIDs is the union of all ITIDs present in all IID-TLVs.

In v2:

   <figure>
          <artwork><![CDATA[  Type:   7 
  Length: 2 - 254 
  Value:  
                                         No. of octets
              +-------------------------+
              | IID (0 - 65535)         |     2
              +-------------------------+
              | Supported ITID          |     2
              +-------------------------+
              :                         :
              +-------------------------+
              | Supported ITID          |     2
              +-------------------------+

  When the IID = 0, the list of supported ITIDs MUST NOT be present.

  An IID-TLV with IID = 0 MUST NOT appear in an SNP or LSP. When 
  the TLV appears (with a non-zero IID) in an SNP or LSP, exactly 
  one ITID MUST be present indicating the instance-specific topology
  with which the PDU is associated. If no ITIDs or multiple ITIDs are
  present or the IID is zero, then the PDU MUST be ignored.

  When the IID is non-zero and the TLV appears in an IIH, the set 
  of ITIDs supported on the circuit over which the IIH is sent is 
  included. There MUST be at least one ITID present. 

  ITID #0 is reserved for a specific use case as described later
  in this document. ITID #0 MUST NOT be supported in combination
  with any non-zero ITID. If multiple ITIDs are advertised in
  an IIH and one of the ITIDs is #0 then the PDU MUST be ignored.

  Multiple IID-TLVs MAY appear in IIHs. If multiple IID-TLVs are
  present and the IID value in all IID-TLVs is not the same, then
  the PDU MUST be ignored.
]]></artwork>
        </figure>
    <t>A single IID-TLV will support advertisement of up to 126 ITIDs. If
       multiple IID-TLVs are present in an IIH PDU, the supported set of
       ITIDs is the union of all ITIDs present in all IID-TLVs.</t>

id2xml:

        </t>
        <figure>
          <artwork><![CDATA[
  Type:   7
  Length: 2 - 254
  Value:
                                         No. of octets
              +-------------------------+
              | IID (0 - 65535)         |     2
              +-------------------------+
              | Supported ITID          |     2
              +-------------------------+
              :                         :
              +-------------------------+
              | Supported ITID          |     2
              +-------------------------+
]]></artwork>
          <postamble>     When the IID = 0, the list of supported ITIDs MUST NOT be present.</postamble>
        </figure>
        <t>
          <list style="hanging"><t hangText="An IID-TLV with IID = 0 MUST NOT appear in an SNP or LSP. When"/>
<t>     the TLV appears (with a non-zero IID) in an SNP or LSP, exactly
     one ITID MUST be present indicating the instance-specific topology
     with which the PDU is associated. If no ITIDs or multiple ITIDs are
     present or the IID is zero, then the PDU MUST be ignored.</t><t hangText="When the IID is non-zero and the TLV appears in an IIH, the set"/>
<t>     of ITIDs supported on the circuit over which the IIH is sent is
     included. There MUST be at least one ITID present.</t><t hangText="ITID #0 is reserved for a specific use case as described later"/>
<t>     in this document. ITID #0 MUST NOT be supported in combination
     with any non-zero ITID. If multiple ITIDs are advertised in
     an IIH and one of the ITIDs is #0 then the PDU MUST be ignored.</t><t hangText="Multiple IID-TLVs MAY appear in IIHs. If multiple IID-TLVs are"/>
<t>     present and the IID value in all IID-TLVs is not the same, then
     the PDU MUST be ignored.</t></list>
        </t>
        <t>
   A single IID-TLV will support advertisement of up to 126 ITIDs.  If
   multiple IID-TLVs are present in an IIH PDU, the supported set of
   ITIDs is the union of all ITIDs present in all IID-TLVs.</t>

Citations throughout text
—————————

6) It appears that citations were not converted to xref tags throughout.  For example:

v2:
    <section anchor="Security" title="Security Considerations">
      <t>
Security concerns for IS-IS are addressed in [ISO10589, [RFC5304],

      and [RFC5310].</t>
    </section>

id2xml:
    <section title="Security Considerations" anchor="section-7.">
      <t>
   Security concerns for IS-IS are addressed in [ISO10589, [RFC5304], and [RFC5310].</t>
    </section>


Reference Entries in the References section
————————
7) We note that <reference> elements were not used and the references section was created using a <section> element instead of <references> and appears in the <middle> as opposed to <back>.  

Is it possible to make these be includes (e.g., <?rfc include='reference.RFC.XXXX’?>)?  That way, the RPC will know the entries are being pulled from the citation library and contain the correct information.  We understand that v3 will have to contain the expanded references.  

in v2:

  </middle>

  <back>
    <references title="Normative References">
      <?rfc include="reference.RFC.2119"?>

      <?rfc include='reference.RFC.5304'?>

      <?rfc include='reference.RFC.5120'?>

      <?rfc include='reference.RFC.5303'?>

      <?rfc include='reference.RFC.5306'?>

      <?rfc include='reference.RFC.5310'?>

      <?rfc include='reference.RFC.6213'?>

      <?rfc include='reference.RFC.6232'?>

      <?rfc include='reference.RFC.6233'?>

      <?rfc include="reference.RFC.6822"?>

      <?rfc include="reference.RFC.6823"?>

      <?rfc ?>

      <?rfc ?>

      <reference anchor="ISO10589">
        <front>
          <title>Intermediate system to Intermediate system intra-domain
          routeing information exchange protocol for use in conjunction with
          the protocol for providing the connectionless-mode Network Service
          (ISO 8473), ISO/IEC 10589:2002, Second Edition.</title>

          <author fullname="ISO &quot;International Organization for Standardization&quot;"/>

          <date month="Nov" year="2002"/>
        </front>
      </reference>
    </references>

in id2xml:

    <section title="References" anchor="section-9.">
      <section title="Normative References" anchor="section-9.1.">
        <t>
          <list style="hanging" hangIndent="11"><t hangText="[ISO10589]"/>
<t>              "Intermediate system to Intermediate system intra-domain routeing information exchange protocol for use in conjunction with the protocol for providing the connectionless-mode Network Service (ISO 8473), ISO/IEC 10589:2002, Second Edition.", Nov 2002.</t><t hangText="[RFC2119]">Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <eref target="http://www.rfc-editor.org/info/rfc2119"/>.</t><t hangText="[RFC5120]">Przygienda, T., Shen, N., and N. Sheth, "M-ISIS: Multi Topology (MT) Routing in Intermediate System to Intermediate Systems (IS-ISs)", RFC 5120,
              DOI 10.17487/RFC5120, February 2008,
              <eref target="http://www.rfc-editor.org/info/rfc5120"/>.</t><t hangText="[RFC5303]">Katz, D., Saluja, R., and D. Eastlake 3rd, "Three-Way Handshake for IS-IS Point-to-Point Adjacencies", RFC 5303,
              DOI 10.17487/RFC5303, October 2008,
              <eref target="http://www.rfc-editor.org/info/rfc5303"/>.</t><t hangText="[RFC5304]">Li, T. and R. Atkinson, "IS-IS Cryptographic Authentication", RFC 5304, DOI 10.17487/RFC5304, October
              2008, <eref target="http://www.rfc-editor.org/info/rfc5304"/>.</t><t hangText="[RFC5306]">Shand, M. and L. Ginsberg, "Restart Signaling for IS-IS",
              RFC 5306, DOI 10.17487/RFC5306, October 2008,
              <eref target="http://www.rfc-editor.org/info/rfc5306"/>.</t><t hangText="[RFC5310]">Bhatia, M., Manral, V., Li, T., Atkinson, R., White, R.,
              and M. Fanto, "IS-IS Generic Cryptographic Authentication", RFC 5310, DOI 10.17487/RFC5310, February
              2009, <eref target="http://www.rfc-editor.org/info/rfc5310"/>.</t><t hangText="[RFC6213]">Hopps, C. and L. Ginsberg, "IS-IS BFD-Enabled TLV",
              RFC 6213, DOI 10.17487/RFC6213, April 2011,
              <eref target="http://www.rfc-editor.org/info/rfc6213"/>.</t><t hangText="[RFC6232]">Wei, F., Qin, Y., Li, Z., Li, T., and J. Dong, "Purge Originator Identification TLV for IS-IS", RFC 6232,
              DOI 10.17487/RFC6232, May 2011,
              <eref target="http://www.rfc-editor.org/info/rfc6232"/>.</t><t hangText="[RFC6233]">Li, T. and L. Ginsberg, "IS-IS Registry Extension for Purges", RFC 6233, DOI 10.17487/RFC6233, May 2011,
              <eref target="http://www.rfc-editor.org/info/rfc6233"/>.</t></list>
        </t>
        <figure>
          <artwork><![CDATA[
[RFC6822]  Previdi, S., Ed., Ginsberg, L., Shand, M., Roy, A., and D.
           Ward, "IS-IS Multi-Instance", RFC 6822,
           DOI 10.17487/RFC6822, December 2012,
           <http://www.rfc-editor.org/info/rfc6822>.
]]></artwork>
        </figure>
        <t>
          <list style="hanging" hangIndent="11">
            <t hangText="[RFC6823]">Ginsberg, L., Previdi, S., and M. Shand, "Advertising Generic Information in IS-IS", RFC 6823,
              DOI 10.17487/RFC6823, December 2012,
              <eref target="http://www.rfc-editor.org/info/rfc6823"/>.</t>
          </list>
        </t>
      </section>
      <section title="Informative References" anchor="section-9.2.">
        <t>
          <list style="hanging" hangIndent="11">
            <t hangText="[RFC5309]">Shen, N., Ed. and A. Zinin, Ed., "Point-to-Point Operation over LAN in Link State Routing Protocols", RFC 5309,
              DOI 10.17487/RFC5309, October 2008,
              <eref target="http://www.rfc-editor.org/info/rfc5309"/>.</t>
            <t hangText="[RFC7042]">Eastlake 3rd, D. and J. Abley, "IANA Considerations and IETF Protocol and Documentation Usage for IEEE 802 Parameters", BCP 141, RFC 7042, DOI 10.17487/RFC7042,
              October 2013, <eref target="http://www.rfc-editor.org/info/rfc7042"/>.</t>
          </list>
        </t>
      </section>
    </section>
  </middle>
  <back>

8) In v2, there is currently a setting to keep DOIs, draft strings, and URLs on the same line (if possible for the latter).

9) We generally see a single space after the author initials instead of two spaces there.

original text:

   [RFC5310]  Bhatia, M., Manral, V., Li, T., Atkinson, R., White, R.,
              and M. Fanto, "IS-IS Generic Cryptographic
              Authentication", RFC 5310, DOI 10.17487/RFC5310, February
              2009, <http://www.rfc-editor.org/info/rfc5310>.

id2xml text output:

   [RFC5310]  Bhatia, M., Manral, V., Li, T., Atkinson, R., White, R.,
              and M.  Fanto, "IS-IS Generic Cryptographic
              Authentication", RFC 5310, DOI 10.17487/RFC5310, February
              2009, <http://www.rfc-editor.org/info/rfc5310>.