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

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 4 Sep 2017 17:32:17 +0200

Hi Megan,

On 2017-08-24 07:14, Megan Ferguson wrote:
> Hi Henrik,
> 
> Input file: draft-ietf-trill-rbridge-multilevel-07 (& RFC 8123)
> Version: id2xml 1.2.2
> Issues: draft strings in references, missing xrefs, extra vspace, list indicator (REQ#)
> Files available: 
> https://www.rfc-editor.org/rfc/v3test/draft-ietf-trill-rbridge-multilevel-07v3.original
> https://www.rfc-editor.org/rfc/v3test/draft-ietf-trill-rbridge-multilevel-07v3.txt
> https://www.rfc-editor.org/rfc/v3test/draft-ietf-trill-rbridge-multilevel-07v3-rfcdiff.html
> https://www.rfc-editor.org/rfc/v3test/draft-ietf-trill-rbridge-multilevel-07v3.xml
> 
> Notes: This file is a revisit.  I actually moved this document through our editing process and 
> spotted a few more items based on actually using the xml file in that process.  
> 
> Level: minor
> 
> 1) Building on the use of citation tags to pull references from
> bibxml3 (which is working out very nicely so far), is there any way
> that we could identify draft strings in reference entries and pull
> the corresponding most-recent version ref from bibxml3 even if the
> citation tag is not in the format I-D.ietf-blah…? An example
> reference is below. Obviously, there would be limitations such as the
> draft string not appearing in the same order, missing a version
> number, etc.

Umm.  This is a bit problematic, since the bibxml3 entry is going to
contain an anchor value in the format I-D.ietf-blah… .  If we insert
that instead of the found reference, the citations in the text are
not going to match up with the citation tag from the bibxml3 entry.

I actually wrote the code up to the point where I generated the entity
definition at the start of the file, and then realised the problem above,
and that this would result in a broken xml file.

I could change all the citation tags in the text from the original tag
to the I-D.ietf-blah… format for draft references identified this way,
though, if you think that is the right thing to do.

Let me know.

If yes, it will be in the next release.

> 
> draft-ietf-trill-rbridge-multilevel-07v3.txt(1677): Warning: Failed parsing a reference.  Are all 
> elements
>    separated by commas (not periods, not just spaces)?:
>    [DraftUnique] - M. Zhang, D. Eastlake, R. Perlman, M. Cullen, H.
>          Zhai, D. Liu, "TRILL Multilevel Using Unique Nicknames", draft-
>          ietf-trill-multilevel-unique-nickname, Work In Progress.
> 
> 2) This file was missing <xref>s for the following. The first one uses Sections X through Y.  
> The other is missing the -s on Section, so not really surprising that it was missed.
> 
> Original:
> 
>    Partitioning the network into areas directly solves the first four
>    scalability issues listed above as described in Sections 1.2.1
>    through 1.2.4. Multilevel also contributes to solving issues 5 and 6
>    as discussed in Section 1.2.5 and 1.2.6 respectively.

Umm.  I'm not sure what the right markup is in the first case.  The second
case might be handled with 2 <xref>s, but the code doesn't look for this
now.  Experience with generating html markup for RFCs suggest that there
are a number of variations on this theme, so I'd prefer to leave it for
manual handling for now.

> 
> 
> In id2xml xml output:
> 
> <section title="Improvements Due to Multilevel" anchor="section-1.2"><t>
>    Partitioning the network into areas directly solves the first four
> 
>    scalability issues listed above as described in Sections 1.2.1
> 
>    through 1.2.4. Multilevel also contributes to solving issues 5 and 6
> 
>    as discussed in <xref target="section-1.2.5"/> and 1.2.6 respectively.</t>
> 
> 
> 3) A little extra whitespace is inserted before a list item in two places in this example:

Mmm.  Right.  The first case below was fairly straightforward to fix; the
second not so.  The issue with the second is that it uses a symbols list
which itself is indented with respect to the surrounding text, something
which xml2rfc doesn't support directly.  id2xml handles this by wrapping
the inner symbols list in an additional list; but in this case the result
is the addition of an extra line.  I think the best thing to do here is
to remove the outer list, and let the inner symbols list get the natural
xml2rfc indentation (i.e., the indentation of '- When both the ingress ...'
would be 2 less in the final text than in the original text.

A fix for the first case will be included in the next id2xml release.

> Original:
> 
>    There are at least two ways areas could be identified.
> 
>       One method would be to assign each area a 16-bit nickname. This
>       would not be the nickname of any actual TRILL switch. Instead, it
>       would be the nickname of the area itself.  Border TRILL switches
>       would know the area nickname for their own area(s).  For an
>       example of a more specific multilevel proposal using unique
>       nicknames, see [DraftUnique].
> 
>       Alternatively, areas could be identified by the set of nicknames
>       that identify the border routers for that area. (See [SingleName]
>       for a multilevel proposal using such a set of nicknames.)
> 
>    The TRILL Header nickname fields in TRILL Data packets being
>    transported through a multilevel TRILL campus with aggregated
>    nicknames are as follows:
> 
>      -  When both the ingress and egress TRILL switches are in the same
>         area, there need be no change from the existing base TRILL
>         protocol standard in the TRILL Header nickname fields.
> 
>      - When being transported between different Level 1 areas in Level
>         2, the ingress nickname is a nickname of the ingress TRILL
> 
> 
> 
> id2xml text output:
> 
>    There are at least two ways areas could be identified.
> 
> 
>       One method would be to assign each area a 16-bit nickname.  This
>       would not be the nickname of any actual TRILL switch.  Instead, it
>       would be the nickname of the area itself.  Border TRILL switches
>       would know the area nickname for their own area(s).  For an
>       example of a more specific multilevel proposal using unique
>       nicknames, see [UNIQUE].
> 
>       Alternatively, areas could be identified by the set of nicknames
>       that identify the border routers for that area.  (See [SingleName]
>       for a multilevel proposal using such a set of nicknames.)
> 
>    The TRILL Header nickname fields in TRILL Data packets being
>    transported through a multilevel TRILL campus with aggregated
>    nicknames are as follows:
> 
> 
> 
>       -  When both the ingress and egress TRILL switches are in the same
>          area, there need be no change from the existing base TRILL
>          protocol standard in the TRILL Header nickname fields.
> 
> 
> In xml:
> 
> 	<t><list style="hanging" hangIndent="3"><t hangText="There are at least two ways areas could be identified.">
> 	<vspace blankLines="0"/>
> 	<vspace blankLines="1"/>
> 	One method would be to assign each area a 16-bit nickname. This
>       would not be the nickname of any actual TRILL switch. Instead, it
>       would be the nickname of the area itself.  Border TRILL switches
>       would know the area nickname for their own area(s).  For an
>       example of a more specific multilevel proposal using unique
>       nicknames, see <xref target="UNIQUE"/>.
> 	<vspace blankLines="1"/>
> 	Alternatively, areas could be identified by the set of nicknames
>       that identify the border routers for that area. (See <xref target="SingleName"/>
>       for a multilevel proposal using such a set of nicknames.)
> 	</t>
> 
> 	</list>
> 	</t>
> 
> 	<t>
>    The TRILL Header nickname fields in TRILL Data packets being
>    transported through a multilevel TRILL campus with aggregated
>    nicknames are as follows:</t>
> 
> 	<t><list style="empty" hangIndent="2">
> 	<t><list style="symbols"><t>When both the ingress and egress TRILL switches are in the same
>         area, there need be no change from the existing base TRILL
>         protocol standard in the TRILL Header nickname fields.</t>
> 
> 	<t>When being transported between different Level 1 areas in Level
>         2, the ingress nickname is a nickname of the ingress TRILL
>         switch's area while the egress nickname is either a nickname of
>         the egress TRILL switch's area or a tree nickname.</t>
> 
> 	<t>When being transported from Level 1 to Level 2, the ingress
>         nickname is the nickname of the ingress TRILL switch itself
>         while the egress nickname is either a nickname for the area of
>         the egress TRILL switch or a tree nickname.</t>
> 
> 	<t>When being transported from Level 2 to Level 1, the ingress
>         nickname is a nickname for the ingress TRILL switch's area while
>         the egress nickname is either the nickname of the egress TRILL
>         switch itself or a tree nickname.</t>
> 
> 	</list>
> 	</t>
> 
> 	</list>
> 	</t>
> 
> 4) I’m wondering if there is a way to include “REQ#” as a list
> indicator? I tried a test file based on RFC 8123 (we don’t have any
> files doing this in the current queue), and it doesn’t seem to be
> one.

Not easily.  This is a very special case, and I think it's better to
handle these by hand.
  
> 
> In the text:
> 
> 5.  Logme Marking Requirements
> 
> 5.1.  Message Logs
> 
>    REQ1: If a SIP message is logged then the entire SIP message (SIP
>          headers and message body) MUST be logged using standard logging
>          format such as SIP CLF defined in [RFC6873].
> 
>    REQ2: Header fields SHOULD be logged in the form in which they
>          appear in the message, they SHOULD NOT be converted between
>          long and compact forms described in [RFC3261] clause 7.3.3.
> 
> 
> 
> In the xml this is made a hanging list:
> 
> 	<section title="Logme Marking Requirements" anchor="section-5"><section title="Message Logs" anchor="section-5.1"><t><list style="hanging" hangIndent="6"><t hangText="REQ1: If a SIP message is logged then the entire SIP message (SIP">
> 	<vspace blankLines="0"/>
> 	headers and message body) MUST be logged using standard logging
>          format such as SIP CLF defined in <xref target="RFC6873"/>.
> 	</t>
> 
> 	<t hangText="REQ2: Header fields SHOULD be logged in the form in which they">
> 	<vspace blankLines="0"/>
> 	appear in the message, they SHOULD NOT be converted between long
>          and compact forms described in <xref target="RFC3261"/> clause 7.3.3.
> 	</t>
> 
> 	</list>
> 	</t>
> 
> Thanks!

Thanks for the feedback.

Once I have your response to my thoughts on 1) above, I'll do a new
release.

Best regards,

	Henrik

---

From: Megan Ferguson <[email-masked]>
Date: Mon, 4 Sep 2017 12:12:59 -0700

Hi Henrik,

Notes marked below with MF.

Thanks!

Megan

> though, if you think that is the right thing to do.
MF - From our perspective, it would be ideal to have the reference pulled from bibxml3 and the 
citation tags updated throughout the text to the [I-D….] style, if this is possible.  We very 
frequently update these tags anyway.

> are a number of variations on this theme, so I'd prefer to leave it for
MF - Okay.  I will note this in our procedures.
> A fix for the first case will be included in the next id2xml release.

MF - Great, thanks!
> Not easily.  This is a very special case, and I think it's better to

MF - I figured.  I will note for our procedures.
>>         and compact forms described in <xref target="RFC3261"/> clause 7.3.3.

MF - Thank you!

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 4 Sep 2017 22:27:06 +0200

Hi Megan,

> frequently update these tags anyway.

Ok, good.  I'll make it so.

Best regards,

	Henrik

---

From: Megan Ferguson <[email-masked]>
Date: Mon, 18 Sep 2017 09:45:18 -0700

Thanks, Henrik!