Subject: [netmod] minor question - YANG Document Guidelines: Imports

From: "Joel M. Halpern" <[email-masked]>
Date: Thu, 28 Jan 2016 13:57:22 -0500

I ran into something while reading a YANG internet-draft recently, and I 
wonder if a bit of advice in the YANG Document Guidelines (rfc6087bis) 
would be reasonable.

Section 4.8 of the guidelines states that any imported modules must also 
have a reference in the references section.  Which is good.  But there 
is no obvious way for a human reader to relate the two.

Would it be sensible to recommend in this document (I don't know if it 
would be 4.8 or a new section later in the document) that import 
statements have a comment with them either naming the internet draft / 
RFC they are importing from, or pointing to the reference which names it?

Thank you,
Joel

---

From: thomas nadeau <[email-masked]>
Date: Thu, 28 Jan 2016 14:00:52 -0500

Thats a great idea. I ran into the same thing yesterday and had to fish around to find the actual RFC it came from.

tom

> On Jan 28, 2016, at 1:57 PM, Joel M. Halpern <[email-masked]> wrote:
> 
> I ran into something while reading a YANG internet-draft recently, and I wonder if a bit of advice in the YANG Document Guidelines (rfc6087bis) would be reasonable.
> 
> Section 4.8 of the guidelines states that any imported modules must also have a reference in the references section.  Which is good.  But there is no obvious way for a human reader to relate the two.
> 
> Would it be sensible to recommend in this document (I don't know if it would be 4.8 or a new section later in the document) that import statements have a comment with them either naming the internet draft / RFC they are importing from, or pointing to the reference which names it?
> 
> Thank you,
> Joel
> 
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod

---

From: thomas nadeau <[email-masked]>
Date: Thu, 28 Jan 2016 14:00:52 -0500

tom

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 28 Jan 2016 21:01:39 +0100

> RFC they are importing from, or pointing to the reference which names it?

Perhaps RFC 6087bis can give additional guidelines. The common way to
get the references into the enclosing document is to include a
statement before the definitions that says something like:

   This module imports <stuff> from the <foo-module> defined in
   [RFCXYZ] and <stuff> form the <bar-module> defined in [RFCABC].

To help readers that have the module and who do not want to bother
looking up the document, including comments may help. It is kind of
funny that YANG does not allow reference statements on imports...

/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: Robert Wilton <[email-masked]>
Date: Fri, 29 Jan 2016 08:47:50 +0000

> funny that YANG does not allow reference statements on imports...
It is too late to add this to Yang 1.1?

That would seem to be the cleanest solution.

I was under the, possibly mistaken, assumption that various YANG tools 
effectively ignore/strip out the comments and hence comments are better 
embedded directly in the model as either reference or description 
statements.

Rob

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 29 Jan 2016 09:58:54 +0100

> On 28 Jan 2016, at 21:01, Juergen Schoenwaelder <[email-masked]> wrote:
> 

I am usually including a table like here:

https://tools.ietf.org/html/draft-ietf-netmod-routing-cfg-20#section-2.3

This not only binds modules with their documents but also shows prefixes that are used in the present document when referring to entities in those modules.

Lada

--
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C