Subject: Re: [netmod] CODE BEGINS ENDS in types draft

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 10 Nov 2009 02:15:22 +0100

On Tue, Nov 10, 2009 at 01:57:16AM +0100, Balazs Lengyel wrote:
> Hello Juergen,
> For the partial-lock draft I was instructed to use the <CODE BEGINS>
> and <CODE ENDS> tags for YANG modules. Will you add them to the
> types draft?

There are two different things here:

a) The CODE BEGINS/ENDS tag for the license stuff. My understanding
   is that this tag is not needed for well-known code types, such as
   MIB modules or YANG modules.

b) A marker that supports automatic extraction of code fragments like
   we did for MIB modules.

The dsdl draft uses a creative version kind of combining both:

   == CODE BEGINS: file "define.rng"
   == CODE ENDS

Perhaps if we use something like

  <CODE BEGINS> file "define.rng"
  <CODE ENDS>

we follow the IETF Trust policy closely (even though not necessarily
required) and at the same time get a file name for automatic tools.

(CCing the WG so we arrive at a common approach, right now the dsdl
 document is different from the yang and yang-types document and they
 are again different from the netconf-monitoring document.)

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 10 Nov 2009 10:59:03 +0900

>   <CODE BEGINS> file "define.rng"

I decided not to use this particular form in the DSDL mapping draft as
it looks like XML which it delimits. The IETF Trust Legal Provisions
state "...<CODE BEGINS> and <CODE ENDS>, or otherwise clearly labeled as
a Code Component", so it should be OK.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 10 Nov 2009 07:17:25 +0100

On Tue, Nov 10, 2009 at 02:59:03AM +0100, Ladislav Lhotka wrote:
> Juergen Schoenwaelder p????e v ??t 10. 11. 2009 v 02:15 +0100:

But for the purpose of automatic extraction, we better agree on _one_
format... All caps looks like ANS.1 - so what. ;-)

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 10 Nov 2009 21:54:16 +0900

> format... All caps looks like ANS.1 - so what. ;-)

OK, no problem with that.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 10 Nov 2009 14:43:31 +0100 (CET)

> OK, no problem with that.

Ok, so we agree to use the syntax above in the next revisions of our
drafts then?

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 10 Nov 2009 23:22:37 +0900

> Ok, so we agree to use the syntax above in the next revisions of our

Fine with me.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 10 Nov 2009 15:37:24 +0100

> Ok, so we agree to use the syntax above in the next revisions of our

I do not care much which format we pick as long as we stick to _one_
format. The above is OK for me but I am happy to use something else.
Now that I think again about it, one could probably also go with just

<CODE BEGINS>
<CODE ENDS>

and have a script extracting modules search for the keyword 'module'
(or 'submodule') and the following name to derive a filename. This is
not much different from how smistrip for example derives a file name.

I also noted differences in the meta data section between the
yang-types and the netconf-monitoring documents and again it would be
nice if we would be consistent since everybody will follow these
initial YANG modules (I am using a reference statement in a revision
statement for example and I have different copyright boilerplate
text). And yes, ideally this all would be documented in the yang usage
document (but right now the template in there is yet different). But
I am optimisitc things will eventually converge. ;-)

/js

---

From: Ladislav Lhotka <[email-masked]>
Date: Tue, 10 Nov 2009 23:43:03 +0900

> not much different from how smistrip for example derives a file name.

But this will not be used only for YANG modules. I prefer Martin's
suggestion.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 10 Nov 2009 15:44:53 +0100 (CET)

> not much different from how smistrip for example derives a file name.

This works fine for YANG (sub)modules, but not for e.g. an ABNF
grammar or the dsdl-files.

> text).

Agreed.  I will align the monitoring module with your modules.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Tue, 10 Nov 2009 07:19:57 -0800

> Agreed.  I will align the monitoring module with your modules.

Shouldn't this be an IETF-wide practice?

Isn't the word 'file' redundant?

> /martin

Andy

---

From: Phil Shafer <[email-masked]>
Date: Tue, 10 Nov 2009 10:13:46 -0500

>Isn't the word 'file' redundant?

Yes and yes, but doesn't is seem broken that we are using "<>" but
not xml tags?  "<code file='define.rng'> ... </code>"?
Or don't use "<>", like:

--- code begins file define.rng ---
blah
--- code ends ---

The xml use of "<>" in an xml-oriented protocol is like nails on
chalkboard.

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 10 Nov 2009 07:53:41 -0800

> The xml use of "<>" in an xml-oriented protocol is like nails on

I agree.
I like Juergen's original format best.

Here is the requirement:

TLP, sec 4b:
                Identification. Text in IETF Contributions and IETF Documents of the types
identified in Section 4.a above shall constitute “Code Components”. In addition, any text found
between the markers <CODE BEGINS> and <CODE ENDS>, or otherwise clearly labeled as a
Code Component, shall be considered a “Code Component”.

An alternative solution would be to add a section to the Usage
Guidelines I-D like:

  The following convention MUST be used to identify
  a YANG module or submodule as a 'Code Component'
  within a document:

  == code-component "module-name.yang"

  module module-name { ... }

  == code-ends

(Actual format is not important to me, but 1 format that never changes
again would be nice.)

Andy