Subject: [netmod] rfcstrip does not work on https://tools.ietf.org/html/draft-ietf-netmod-artwork-folding-12

From: Balázs Lengyel <[email-masked]>
Date: Fri, 27 Mar 2020 17:36:25 +0000

Hello,

https://tools.ietf.org/html/draft-ietf-netmod-artwork-folding-12 contains a
section with <CODE BEGINS> <CODE ENS>.

However rfcstrip cannot extract this part. Is that a problem?

Regards Balazs

-- 

Balazs Lengyel                    Senior Specialist
Ericsson Hungary Ltd. 

Mobile: +36-70-330-7909              email: [email-masked]

---

From: Kent Watsen <[email-masked]>
Date: Fri, 27 Mar 2020 18:15:19 +0000

Hi Balazs,

> On Mar 27, 2020, at 1:36 PM, Balázs Lengyel <balazs.lengyel=[email-masked]> wrote:
> 
> Hello,
> https://tools.ietf.org/html/draft-ietf-netmod-artwork-folding-12 <https://tools.ietf.org/html/draft-ietf-netmod-artwork-folding-12> contains a section with <CODE BEGINS> <CODE ENS>.

Looking at -12, I see "<CODE ENDS>” (not <CODE ENS>), is this just a typo in your message?

> However rfcstrip cannot extract this part. Is that a problem?

It seems that the <CODE BEGINS> line is messed up:

OLD:
   <CODE BEGINS>

NEW:
   <CODE BEGINS> file "rfcfold"

Fixes it.

I’ll let the RFC Editor know - thanks!

Kent // contributor 

> Regards Balazs
>  
> -- 
> Balazs Lengyel                    Senior Specialist                       Ericsson Hungary Ltd. 
> Mobile: +36-70-330-7909              email: [email-masked] <mailto:[email-masked]>
>  
> _______________________________________________
> netmod mailing list
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/netmod <https://www.ietf.org/mailman/listinfo/netmod>

---

From: Erik Auerswald <[email-masked]>
Date: Mon, 30 Mar 2020 12:22:55 +0200

Hi Kent, Balázs,

>     <CODE BEGINS> file "rfcfold"

Do you know of a written explanation on how to use the <CODE BEGINS> ...
<CODE ENDS> markers?  I tried to find one without success.  I found only
usage hints, and the licensing connection.

RFC 8407 says:

     The "<CODE BEGINS>" tag SHOULD be followed by a string identifying
     the file name specified in Section 5.2 of [RFC7950]."

The predecessor RFC 6087 contains similar text.  Thus it seems the
netmod WG convention is to specify a file name.  The rfcstrip utility
mentioned in RFC 8407 requires the file name, although the file name
seems to be optional.

But some RFCs do not specify a file name for code sections.  Some
random examples are RFC 5662, RFC 6287, RFC 7861, and RFC 8290. Those
are from WGs other than netmod, though.

Just curious. :-)

Thanks,
Erik

---

From: Kent Watsen <[email-masked]>
Date: Mon, 30 Mar 2020 23:47:11 +0000

Erik,

I can’t find a definition.

I thought someone said that `xml2rfc` was going to support a “markers” attribute for the <sourcecode> element, but I don’t see that here yet: https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/blob/master/draft-iab-rfc7991bis.xml#L8514 <https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/blob/master/draft-iab-rfc7991bis.xml#L8514>.

Kent

> On Mar 30, 2020, at 6:22 AM, Erik Auerswald <[email-masked]> wrote:
> 
> Hi Kent, Balázs,
> 
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 31 Mar 2020 09:22:15 +0200

On 2020-03-31, at 01:47, Kent Watsen <[email-masked]> wrote:
> 
> I thought someone said that `xml2rfc` was going to support a “markers” attribute for the <sourcecode> element, but I don’t see that here yet: https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/blob/master/draft-iab-rfc7991bis.xml#L8514.

https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation-notes-10#section-3.1.22

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 31 Mar 2020 09:36:15 +0200

Oh, and you can find examples for markers=“true” in the published RFCs

rfc8650.xml
rfc8652.xml
rfc8675.xml
rfc8676.xml
rfc8681.xml
rfc8682.xml
rfc8695.xml
rfc8696.xml
rfc8748.xml

So this is no longer just a proposal, as the below draft seems to suggest.

Grüße, Carsten

> On 2020-03-31, at 09:22, Carsten Bormann <[email-masked]> wrote:
>

---

From: Balázs Lengyel <[email-masked]>
Date: Tue, 31 Mar 2020 09:31:26 +0000

As I understand that works if you use Xml2Rfc v3 only. 
Balazs

-----Original Message-----
From: Carsten Bormann <[email-masked]> 
Sent: 2020. március 31., kedd 9:36
To: Kent Watsen <[email-masked]>
Cc: Erik Auerswald <[email-masked]>; Balázs Lengyel <[email-masked]>; [email-masked]
Subject: Re: [netmod] rfcstrip does not work on https://tools.ietf.org/html/draft-ietf-netmod-artwork-folding-12

rfc8650.xml
rfc8652.xml
rfc8675.xml
rfc8676.xml
rfc8681.xml
rfc8682.xml
rfc8695.xml
rfc8696.xml
rfc8748.xml

Grüße, Carsten

>> I thought someone said that `xml2rfc` was going to support a “markers” attribute for the <sourcecode> element, but I don’t see that here yet: https://protect2.fireeye.com/v1/url?k=2558e5eb-798ceda8-2558a570-86a1150bc3ba-91f9e8a7be6cf53c&q=1&e=7c165797-25c3-4d3e-8bbc-f14b6f8c7cf7&u=https%3A%2F%2Fgithub.com%2Frfc-format%2Fdraft-iab-xml2rfc-v3-bis%2Fblob%2Fmaster%2Fdraft-iab-rfc7991bis.xml%23L8514.
>

---

From: Erik Auerswald <[email-masked]>
Date: Tue, 31 Mar 2020 14:01:26 +0200

Hi all,

>> https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation-notes-10#section-3.1.22

Thanks for the additional info.  The proposal states:

     Proposal:  Add an attribute 'markers' for <sourcecode>, to control
        the emission of <CODE BEGINS> and <CODE ENDS>.  If markers="true"
        and the "name" attribute is set, the filename will also be
        emitted, as specified in [RFC8407] for YANG modules.

Thus the `file' part of the  <CODE ...> markers seems to be optional
there, too, unless the code in question is a YANG module.  In RFC8407 it
is recommended (SHOULD) to add a file name specification to the
<CODE BEGINS> marker, so it is still kind of optional.

I try to understand if the omission of a file name for the code in
draft-ietf-netmod-artwork-folding-12 was "wrong" or just "not great",
and what the current practice is.  It did result in Martin's `rfcstrip'
not extracting it from the text version.

Martin's `rfcstrip' could not extract `rfcfold' from the XML version
either,  because the XML uses `artwork' instead of `sourcecode'.
Adjusting the code to expect the `artwork' tag confirms this.  I used

     sed -i 's,//sourcecode\[,//artwork[,' rfcstrip

to try this out.  (Note that I do not suggest to apply this change to
Martin's `rfcstrip', but rather want to show what I did.)

> Oh, and you can find examples for markers=“true” in the published RFCs

RFC 8650 "Dynamic Subscription to YANG Events and Datastores over
RESTCONF" contains a YANG module inside a <CODE ...> section with
file name specification on the following line in the text rendering.

Since the code of Martin's `rfcstrip' that recognizes a <CODE ...>
section requires the keyword `file' on the same line as `<CODE BEGINS>',
I take a closer look at how it handles this RFC.

Martin's rfcstrip does not recognize this <CODE ...> section in the
text rendering, because the keyword `file' is not on the same line as
`<CODE BEGINS>'.  It still extracts the YANG module via the "type 3"
code path for YANG modules without <CODE ...> markers from the text
rendering.

Martin's `rfcstrip' extracts the YANG module with the specified name
from the XML version of the RFC.  It extracts two of the many JSON
examples from the XML version as well.  The examples do not use
<CODE ...> markers in the text rendering.

One of the HTML renderings displays the file name on the same line
as the <CODE BEGINS> marker 
(https://www.rfc-editor.org/rfc/rfc8650.html#name-yang-module), the 
other shows it on the
following line (https://tools.ietf.org/html/rfc8650), as does the
text rendering (https://tools.ietf.org/rfc/rfc8650.txt).  The PDF
rendering shows the file name specification on the same line as
<CODE BEGINS> (https://tools.ietf.org/pdf/rfc8650.pdf).

As far as I understand it, the XML version of the RFC is authoritative
and tools are supposed to work on the XML, not renderings created from
XML.  [I am not sure about the exact RFC number where this change from
text to XML takes effect.]

> rfc8676.xml

The above RFCs contain YANG modules.  They specify file names for the
respective <CODE ...> sections.

> rfc8681.xml

RFC 8681 "Sliding Window Random Linear Code (RLC) Forward Erasure
Correction (FEC) Schemes for FECFRAME" does not contain a YANG module.
It contains C code.  It does not specify a file name for any of the
two code sections.

> rfc8682.xml

RFC 8682 "TinyMT32 Pseudorandom Number Generator (PRNG)" contains C code
inside a <CODE ...> section without specifying a file name.  The
preceding text does suggest a file name.

> rfc8695.xml

RFC 8695 is another YANG module RFC giving a file name for the
<CODE ...> section.

> rfc8696.xml

RFC 8696 "Using Pre-Shared Key (PSK) in the Cryptographic Message Syntax
(CMS)" contains an ASN.1 module inside a <CODE ...> section without file
name.

> rfc8748.xml

RFC 8748 "Registry Fee Extension for the Extensible Provisioning
Protocol (EPP)" contains an XML schema inside <CODE ...> markers without
giving a file name.

It seems to me that <CODE BEGINS> ... <CODE ENDS> sections without file
name specification are common for both older RFCs in text format and
newer RFCs in XML format.  Even for YANG modules it seems to be
recommended, but not required, to specify a file name.  Thus I would not
have called the <CODE ...> line of draft-ietf-netmod-artwork-folding-12
"messed up," but do think that adding a file name improves it. :-)

The empty line after <CODE BEGINS> in I-D.ietf-netmod-artwork-folding-12
looks like a potential problem, because the first line of a shell script
on Unix-like systems needs to specify the interpreter, but Martin's
`rfcstrip' correctly handles this by skipping leading and trailing empty
lines inside the <CODE BEGINS> ... <CODE ENDS> section.

I think I do have a better understanding of the use of <CODE ...>
markers and the possible issues. :-)

Thanks,
Erik

---

From: Martin Björklund <[email-masked]>
Date: Tue, 31 Mar 2020 17:04:49 +0200 (CEST)

Hi,

Version 1.2 of rfcstrip (https://github.com/mbj4668/rfcstrip) can
extract from the "artwork" element, and performs artwork unfolding, if
needed.

See below for some details.

Erik Auerswald <[email-masked]> wrote:
> >>> I thought someone said that `xml2rfc` was going to support a “markers”
> >>> attribute for the <sourcecode> element, but I don’t see that here yet:
> >>> https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/blob/master/draft-iab-rfc7991bis.xml#L8514.
> >>

Right.  Without a file name to extract to, rfcstrip doesn't extract.

> either,  because the XML uses `artwork' instead of `sourcecode'.

Version 1.2 of rfcstrip handles this (with option -a).

> code path for YANG modules without <CODE ...> markers from the text

Right.  I think the filename on a separate line was invented by the
RFC editor when the name of the file was too long.

> markers and the possible issues. :-)

:)

/martin

---

From: Kent Watsen <[email-masked]>
Date: Tue, 31 Mar 2020 16:05:17 +0000

Hi Martin,

> Version 1.2 of rfcstrip (https://github.com/mbj4668/rfcstrip <https://github.com/mbj4668/rfcstrip>) can

Thanks for this update to rfcstrip!

If it’s not too late, may I suggest changing “-a” to “-x”?

Reasons:
   1) ‘a’ stands for “artwork” but, in the long run, we’ll only be striping out “sourcecode” elements
   2) ‘x’ could refer to the input format “XML” (as opposed to the default “txt” format)

Better, perhaps `rfcstrip` could automatically do the right thing, either by keying off the suffix (.xml vs .txt) or by first testing if the file contains XML?

Kent // contributor

---

From: Martin Björklund <[email-masked]>
Date: Tue, 31 Mar 2020 19:41:42 +0200 (CEST)

Hi,

>    striping out “sourcecode” elements

Before this fix, rfcstrip handled sourcecode elements only.  With -a,
it also handles artwork.

> Better, perhaps `rfcstrip` could automatically do the right thing,
> either by keying off the suffix (.xml vs .txt) or by first testing
> if the file contains XML?

It already automatically tests if it is XML; there's no flag for that.

/martin