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

[Henrik Levkowetz <[e-mail]>]

Hi Megan,

On 2017-05-26 20:49, Megan Ferguson wrote:
> Hi Henrik,
> 
> Thank you for your reply and explanations.  Inline below with MF.
> 
> Megan
> 
> Begin forwarded message:
> 
>> From: Henrik Levkowetz <[e-mail]>
>> Subject: Re: [TOOLS-DEVELOPMENT] Preview release of Text Submission Converter, id2xml
>> Date: May 19, 2017 at 2:20:25 PM PDT
>> To: Megan Ferguson <[e-mail]>
>> Cc: [e-mail]
>> 
>> Hi Megan,
>> 
>> On 2017-05-19 21:55, Megan Ferguson wrote:
>>> 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.
>> 
>> In general, I'd very much appreciate the relevant draft name when you
>> point out an issue; that will let me use that in testing and fixing
>> the issue.  As you'll see below, I believe that many of the issues you
>> mention below are fixed in the latest release (1.0.0-rc1), but there
>> are some cases below where the draft name would be good to have.
> 
> MF- Ack.  I used draft-ietf-isis-mi-bis-03 originally.  I have rerun this same file with the newer version and found 
> most of the items previously discussed to be resolved.
> 
> I also tested on draft-ietf-rtgwg-yang-key-chain-24.
> 
> Latest Release Notes:
> ---------------------
> 
> 1) Missing references:
> 
> When running id2xml (v1.0.0-rc1) on draft-ietf-isis-mi-bis-03, I
> received the following warning:
> 
> id2xml draft-ietf-isis-mi-bis-03test.txt
> Converting 'draft-ietf-isis-mi-bis-03test.txt'
> 
> draft-ietf-isis-mi-bis-03test.txt(660): Warning: Failed parsing a reference:
>    [ISO10589]
>               "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.
> Written to 'draft-ietf-isis-mi-bis-03test.xml’
> 
> With the reference being removed but the reference element still
> included (causing v2 not to parse until the empty element was
> removed).

Yes, this is the current behaviour with a reference that cannot be parsed.

If you are happy with the text in the input document (i.e., it looks the way
you would want to see it in an RFC, then please let me know, and I'll see if
I can adjust the set of regexes used to parse reference text.  In the case
above, it seems to me that series information has incorrectly been made part
of the document title.  I would expect the reference to be correctly parsed
if you break out the series info the way you'd like to see it in a published
document.


> Note that I also got a similar error running
> draft-ietf-rtgwg-yang-key-chain-24:
> 
> id2xml draft-ietf-rtgwg-yang-key-chain-24test.txt
> Converting 'draft-ietf-rtgwg-yang-key-chain-24test.txt'
> 
> draft-ietf-rtgwg-yang-key-chain-24test.txt(983): Warning: Failed parsing a reference:
>    [Dobb96b]  Dobbertin, H., "The Status of MD5 After a Recent Attack",
>               CryptoBytes Vol. 2, No. 2, Summer 1996.

Yes.  There's nothing in the current rule set for reference text which knows
how to handle 'Summer 1996'.

> *This second instance was more interesting to me based on the fact
> that the document contains a [Dobb96a] reference that is used very
> similarly, but was picked up just fine.
> 
> 2) I was curious about how a reference to a BCP that included more
> than one RFC would be handled (for example, BCP 9 below).

[snip]

Sandy posted a comment on this, which was to-the-point.

> 3) There are XML snippets in the appendices of
> draft-ietf-rtgwg-yang-key-chain-24. id2xml put the first two them
> into lists, which broke the alignment (the original XML by the
> authors used <artwork>), but the third snippet in the last appendix
> was put into <artwork>.

Right.  This is something I also found meanwhile.  I've enhanced the
regex which identifies code snippets to recognise xml and relatives;
this should be handled correctly in 2.0.0rc3.


[snipping a number of points where you confirm that 1.0.0-rc1 fixed
the issue -- thank you, good to get the confirmation]


>> The choice of inserting both entity definitions at the start, and expanded
>> xml refereces in the <references/> sections was done to make it easier for
>> you to choose one or the other.  If you'd rather I inserted the appropriate
>> entity at the point of reference, I could do so.  You would then instead
>> of:
>> 
>>  <back>
>>    <references title="Normative References">
>>      <?rfc include="reference.RFC.2119"?>
>>      <?rfc include='reference.RFC.5304'?>
>>      ...
>> 
>> see:
>> 
>>  <back>
>>    <references title="Normative References">
>>      &RFC2119;
>>      &RFC5304;
>>      ...
>> 
>> and it would pull the reference entries from the citation library in the
>> same way as with the <?rfc include ?> pi.
>> 
> MF - We believe it is more desirable for our purposes to have the
> entity definitions at the start and the &RFC2119;-style calls in the
> References section.

Ok, I will remove the generated reference xml and instead insert the
reference entities in the next release.

>> 
>>> 8) In v2, there is currently a setting to keep DOIs, draft strings,
>>> and URLs on the same line (if possible for the latter).
>> 
>> Ok; which setting are you thinking of?  I can certainly insert it if
>> desired.
> 
> MF - Sorry - I don’t know of a specific setting.  I simply remember them implementing it into one of the v2 versions. 

Ok.  FWIW, when xml2rfc processes what id2xml currently generates, it
tries to keep DOIs etc. on one line.  That's actually a source of
differences with the input documents in the test suite, in several cases,
because they don't always try as hard to keep the DOIs etc. on the same
line ,:-)

>>> 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>.
>> 
>> There was an issue in 0.9.2 where extra spaces were not stripped from the
>> initials string; that was fixed in 0.9.3, and should also be fixed in 
>> 1.0.0-rc1.  Please let me know if you find that it's not the case.
>> 
> MF - This is resolved.

Ok, splendid.


Thank you again for the feedback!


Best regards,

	Henrik