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

From: Henrik Levkowetz <[email-masked]>
Date: Sat, 1 Jul 2017 23:11:03 +0200

Hi Megan,

On 2017-06-27 00:48, Megan Ferguson wrote:
> Hi Henrik,
> 
> Input file: draft-ietf-bmwg-ipv6-tran-tech-benchmarking-08
> Version: id2xml 1.0.2
> Issues: File not originally generated with XML, table-to-figure, lists, numbered sections after References
> Files available: 
> https://www.rfc-editor.org/rfc/v3test/draft-ietf-bmwg-ipv6-tran-tech-benchmarking-08v3.original
> https://www.rfc-editor.org/rfc/v3test/draft-ietf-bmwg-ipv6-tran-tech-benchmarking-08v3.txt
> https://www.rfc-editor.org/rfc/v3test/draft-ietf-bmwg-ipv6-tran-tech-benchmarking-08v3.xml
> https://www.rfc-editor.org/rfc/v3test/draft-ietf-bmwg-ipv6-tran-tech-benchmarking-08v3-rfcdiff.html
> 
> 1) The original includes a table that is turned into a figure (instead of vice versa):
> 
> Original:
>              Table 1. IPv6 Transition Technologies Categories
>       +---+--------------------+------------------------------------+
>       |   | Generic category   | IPv6 Transition Technology         |
>       +---+--------------------+------------------------------------+
>       | 1 | Dual-stack         | Dual IP Layer Operations [RFC4213] |
>       +---+--------------------+------------------------------------+
>       | 2 | Single translation | NAT64 [RFC6146],  IVI [RFC6219]    |
>       +---+--------------------+------------------------------------+
>       | 3 | Double translation | 464XLAT [RFC6877], MAP-T [RFC7599] |
>       +---+--------------------+------------------------------------+
>       | 4 | Encapsulation      | DSLite[RFC6333], MAP-E [RFC7597]   |
>       |   |                    | Lightweight 4over6 [RFC7596]       |
>       |   |                    | 6RD [RFC5569], 6PE [RFC4798], 6VPE |
>       |   |                    | 6VPE [RFC4659]                     |
>       +---+--------------------+------------------------------------+
> 
> 
> id2xml output:
>              Figure 1: IPv6 Transition Technologies Categories
>     +---+--------------------+------------------------------------+ | |
>               Generic category | IPv6 Transition Technology |
>    +---+--------------------+------------------------------------+ | 1 |
>              Dual-stack | Dual IP Layer Operations [RFC4213] |
>    +---+--------------------+------------------------------------+ | 2 |
>           Single translation | NAT64 [RFC6146], IVI [RFC6219]  |
>    +---+--------------------+------------------------------------+ | 3 |
>          Double translation | 464XLAT [RFC6877], MAP-T [RFC7599] |
>    +---+--------------------+------------------------------------+ | 4 |
>    Encapsulation | DSLite[RFC6333], MAP-E [RFC7597]  | | | | Lightweight
>    4over6 [RFC7596]  | | | | 6RD [RFC5569], 6PE [RFC4798], 6VPE | | | |
>                              6VPE [RFC4659]  |
>       +---+--------------------+——————————————————+

Yes.  There's no sensible pattern for a table with a title immediately
preceding it, with no separating blank line.  If you move the 'Table 1. ...'
line down below the table, with a separating blank line, things will work
much better.

> 
> 2) FYI - It appears that the Acknowledgements section was removed — probably because it appeared as 
> a numbered section after the references.

Yes.  I tried moving it up before the references, with renumbering to
15.  Acknowledgements, and 16... for the references, and things then seems
good.

> 
> 3) There is a bit of a spacing oddity after “Throughput”.  This is not
> highlighted in the diff.
> 
> Original:
> 
> 3. Terminology
> 
>    A number of terms used in this memo have been defined in other RFCs.
>    Please refer to those RFCs for definitions, testing procedures and
>    reporting formats.
> 
>    Throughput (Benchmark)  - [RFC2544]
> 
>    Frame Loss Rate (Benchmark) - [RFC2544]
> 
>    Back-to-back Frames (Benchmark) - [RFC2544]
> 
>    System Recovery (Benchmark) - [RFC2544]
> 
>    Reset (Benchmark) - [RFC6201]
> 
>    Concurrent TCP Connection Capacity (Benchmark) - [RFC3511]
> 
>    Maximum TCP Connection Establishment Rate (Benchmark) - [RFC3511]
> 
> 
> id2xml output:
> 
> 3.  Terminology
> 
>    A number of terms used in this memo have been defined in other RFCs.
>    Please refer to those RFCs for definitions, testing procedures and
>    reporting formats.
> 
>    Throughput (Benchmark)  - [RFC2544]
> 
> 
>    Frame Loss Rate (Benchmark) - [RFC2544]
> 
>    Back-to-back Frames (Benchmark) - [RFC2544]
> 
>    System Recovery (Benchmark) - [RFC2544]
> 
>    Reset (Benchmark) - [RFC6201]
> 
>    Concurrent TCP Connection Capacity (Benchmark) - [RFC3511]
> 
>    Maximum TCP Connection Establishment Rate (Benchmark) - [RFC3511]

Hmm.  Yes.  I see that the code has inserted a <vspace> at the end of
the list entry there, but there's not any more text in that item, so
things become weird.  I'm not sure how this would best be modelled,
as a list or as individual text paragraphs.  id2xml has made different
choices for the different lines, because the first line has double
spaces between 'Throughput (Benchmark)' and the dash, while the other
lines don't.  If you make that a single space, things will look better.

> 4) Numbering started up again with 1 instead of the expected 6:
> 
> Original:
> 
>    The test traffic SHOULD follow the following steps.
> 
>    1. Query for the AAAA record of a domain name (from client to DNS64
>    server)
> 
>    2. Query for the AAAA record of the same domain name (from DNS64
>    server to authoritative DNS server)
> 
>    3. Empty AAAA record answer (from authoritative DNS server to DNS64
>    server)
> 
>    4. Query for the A record of the same domain name (from DNS64 server
>    to authoritative DNS server)
> 
>    5. Valid A record answer (from authoritative DNS server to DNS64
>    server)
> 
>    6. Synthesized AAAA record answer (from DNS64 server to client)
> 
> id2xml output:
> 
>    1.  Query for the AAAA record of a domain name (from client to DNS64
>    server)
> 
>    2.  Query for the AAAA record of the same domain name (from DNS64
>    server to authoritative DNS server)
> 
>    3.  Empty AAAA record answer (from authoritative DNS server to DNS64
>    server)
> 
>    4.  Query for the A record of the same domain name (from DNS64 server
>    to authoritative DNS server)
> 
>    5.  Valid A record answer (from authoritative DNS server to DNS64
>    server)
> 
>    1.  Synthesized AAAA record answer (from DNS64 server to client)

Yes.  This is because the missing indentation of the second line of items 1
to 5 prevents the items from being recognized as list items; they are just
turned into paragraphs in the xml markup, which is not what you want.  Fixing
the indentation lets id2xml recognize all items as list items.

> 5) This list is interesting as it would probably require the use of
> the “counter” mentioned at 
> https://xml2rfc.tools.ietf.org/xml2rfcFAQ.html#anchor23.
> 
> It looks like id2xml turned it into artwork because there was no space between the numbered item 
> and the following text.  
> 
> If we update to add a space between the numbered item and the following text, we get renumbering.  
> Not sure how id2xml could detect such a case.
> 
> id2xml:
> 
>    Details and parameters:
> 
>    1. Caching
>    First, all the DNS queries MUST contain different domain names (or
>    domain names MUST NOT be repeated before the cache of the DUT is
>    exhausted). Then new tests MAY be executed with domain names, 20%,
>    40%, 60%, 80% and 100% of which are cached. We note that ensuring a
>    record being cached requires repeating it both "late enough" after
>    the first query to be already resolved and be present in the cache
>    and "early enough" to be still present in the cache.
> 
>    2. Existence of AAAA record
>    First, all the DNS queries MUST contain domain names which do not
>    have an AAAA record and have exactly one A record.
> 
> xml:
>    Details and parameters:</t>
> 
> 	<figure><artwork><![CDATA[
> 1. Caching
> First, all the DNS queries MUST contain different domain names (or
> domain names MUST NOT be repeated before the cache of the DUT is
> exhausted). Then new tests MAY be executed with domain names, 20%,
> 40%, 60%, 80% and 100% of which are cached. We note that ensuring a
> record being cached requires repeating it both "late enough" after
> the first query to be already resolved and be present in the cache
> and "early enough" to be still present in the cache.
> 
> 2. Existence of AAAA record
> First, all the DNS queries MUST contain domain names which do not
> have an AAAA record and have exactly one A record.
> ]]></artwork>
> 	</figure>

Yes.  Again a case where the missing indentation of list item text prevents
the list from being recognized as such.  Adding indentation so as to get
the usual list look lets id2xml recognize it as a list.

I'm attaching a minimally edited version of the draft where I've applied
the suggestions above, as draft-ietf-bmwg-ipv6-tran-tech-benchmarking-08a.txt.

It will parse better, with the exception of a few of the references, which
still won't be parsed with id2xml 1.0.2; I'm making some tweaks to the
reference patterns and also to recognise 'Internet Draft' on the first page
in id2xml version 1.0.3, which should be out tomorrow.

Thanks for the feedback :-)

Best regards,

	Henrik

> Thank you.
> RFC Editor/mf

---

From: "HANSEN, TONY L" <[email-masked]>
Date: Sun, 2 Jul 2017 02:14:42 +0000

With help from Henrik, the preview release of the new text to XML2RFC converter, id2xml, has been made available at <https://xml2rfc.tools.ietf.org/experimental.html#id2xml>.

Hope people find it useful.

	Tony Hansen