Subject: [xml2rfc-dev] <sourcecode> element

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 23 Oct 2018 14:27:43 +0200

Hi,

I appreciated that xml2rfc v3 had added the <sourcecode> element. It would also
seem the right choice for the inclusion of YANG modules instead of <artwork>.

However, this is currently impossible because the xml2rfc tool automatically
adds <CODE BEGINS> a <CODE ENDS> markers. This interferes with the mandatory
convention that is used for YANG modules, see RFC 8407, sec. 3.2:

   <CODE BEGINS> file "[email-masked]"

       module ietf-foo {
         namespace "urn:ietf:params:xml:ns:yang:ietf-foo";
         prefix "foo";
         organization "...";
         contact "...";
         description "...";
         revision 2016-03-20 {
           description "Latest revision";
           reference "RFC XXXX: Foo Protocol";
         }
         // ... more statements
       }

   <CODE ENDS>

Given that YANG modules appear quite frequently in RFCs and I-Ds these days, it
might be useful to support the above convention. One way to do this can be:

- define an attribute for <sourcecode>, for example "language", to indicate
what language the source code is written in

- automatically add the YANG-specific markers if the language is YANG.

Thanks, Lada

P.S. Sorry if this has been discussed before.

-- 
Ladislav Lhotka
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 23 Oct 2018 15:08:58 +0200

Hi Ladislav,

> convention that is used for YANG modules, see RFC 8407, sec. 3.2:

If you add a 'name' attribute to <sourcecode>, it will output exactly
what you want:

    <sourcecode name="[email-masked]">
    ...
    </sourcecode>

> what language the source code is written in

There already exists a 'type' attribute, but it's orthogonal to the expansion
of the name attribute:

    <sourcecode name="[email-masked]" type="yang">
    ...
    </sourcecode>

In the next release of xml2rfc, there will also be a 'markers' attribute,
which will let you turn on and off the generation of the <CODE *> markers.

Best regards,

	Henrik

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 23 Oct 2018 15:19:45 +0200

Hi Henrik,

>     <sourcecode name="[email-masked]">

It is not clear from RFC 7991 that the "name" attribute should result in this.

> There already exists a 'type' attribute, but it's orthogonal to the expansion

Oh, sorry, I missed this.

> which will let you turn on and off the generation of the <CODE *> markers.

Yes, that's useful.

Thanks, Lada

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 23 Oct 2018 16:39:17 +0200

Hi Ladislav,

> It is not clear from RFC 7991 that the "name" attribute should result in this.

Correct.  If you're using the --v3 output of xml2rfc at this point in
time, you might want to be familiar with the issues I've found while
implementing RFC 7991:

https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation-notes-04

I'll be adding some more information about the expansion of "name" and the
use of "markers" there in the next revision, too.

Best regards,

	Henrik