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 protected]> wrote: > Hi all, > > On 31.03.20 09:36, Carsten Bormann wrote: > > On 2020-03-31, at 09:22, Carsten Bormann <[email protected]> wrote: > > > >> On 2020-03-31, at 01:47, Kent Watsen <[email protected]> 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 > >> > > 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. Right. Without a file name to extract to, rfcstrip doesn't extract. > Martin's `rfcstrip' could not extract `rfcfold' from the XML version > either, because the XML uses `artwork' instead of `sourcecode'. Version 1.2 of rfcstrip handles this (with option -a). > 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 > > rfc8650.xml > > 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. Right. I think the filename on a separate line was invented by the RFC editor when the name of the file was too long. > 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.] > > > rfc8652.xml > > rfc8675.xml > > 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. :-) :) /martin > > Thanks, > Erik > > _______________________________________________ > netmod mailing list > [email protected] > https://www.ietf.org/mailman/listinfo/netmod _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
