Re: [netmod] Canonical order: linkage and meta

[William Lupton]

Thanks. That’s fine. I was just checking for opinions :). W.

> On 27 Jun 2016, at 12:03, Juergen Schoenwaelder 
>  wrote:
> 
> I think changing the canonical format because some people may miss the
> copyright since they have to scroll down a bit is not really worth the
> pain of having different canonical formats out there. And something
> like
> 
> // please scroll down to see the license
> 
> does seem to sovle the problem.
> 
> /js
> 
> On Mon, Jun 27, 2016 at 11:20:02AM +0100, William Lupton wrote:
>> All,
>> 
>> No-one replied to this. Fair enough, because it probably seems a rather 
>> trivial question! But I wanted to point out that a practical consequence of 
>> the description being a long way down a module is that the license text 
>> could easily be missed (assuming it’s in the top-level description, which is 
>> the usual IETF - and BBF - practice). In one BBF module (lots of includes, 
>> each of which has a revision-date and uses 3 lines), the top-level 
>> description begins at line 149 out of 204.
>> 
>> OK, we could put a comment nearer the top of the file that points the reader 
>> further down the file, or we could move the license text into a comment near 
>> the top of the file. But usual YANG practice (and I like this) seems to be 
>> to prefer to put information into YANG statements rather than into comments.
>> 
>> Thoughts?
>> 
>> Thanks,
>> William
>> 
>>> On 9 Jun 2016, at 12:30, William Lupton  wrote:
>>> 
>>> All,
>>> 
>>> RFC 6020bis says “The ABNF grammar [RFC5234] [RFC7405] defines the 
>>> canonical order. To improve module readability, it is RECOMMENDED that 
>>> clauses be entered in this order.”
>>> 
>>> The ABNF places linkage-stmts (import, include) before meta-stmts 
>>> (organization, contact, description, reference) but if there are a lot of 
>>> linkage statements (which will be the case in the main module if there are 
>>> a large number of submodules… as there are for some of the modules that BBF 
>>> is defining) this means that the description can be a fair way down the 
>>> module.
>>> 
>>> Would there be any support for regarding placement of the meta statements 
>>> before the linkage statements as not being a violation of canonical order? 
>>> Note (this might be inadvertent) that the ABNF actually defines 
>>> “meta-stmts” before “linkage-stmts”.
>>> 
>>> Thanks,
>>> William
>> 
>> ___
>> netmod mailing list
>> netmod@ietf.org
>> https://www.ietf.org/mailman/listinfo/netmod
> 
> -- 
> Juergen Schoenwaelder   Jacobs University Bremen gGmbH
> Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany
> Fax:   +49 421 200 3103 
> 

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

Re: [netmod] Canonical order: linkage and meta

[Juergen Schoenwaelder]

I think changing the canonical format because some people may miss the
copyright since they have to scroll down a bit is not really worth the
pain of having different canonical formats out there. And something
like

 // please scroll down to see the license

does seem to sovle the problem.

/js

On Mon, Jun 27, 2016 at 11:20:02AM +0100, William Lupton wrote:
> All,
> 
> No-one replied to this. Fair enough, because it probably seems a rather 
> trivial question! But I wanted to point out that a practical consequence of 
> the description being a long way down a module is that the license text could 
> easily be missed (assuming it’s in the top-level description, which is the 
> usual IETF - and BBF - practice). In one BBF module (lots of includes, each 
> of which has a revision-date and uses 3 lines), the top-level description 
> begins at line 149 out of 204.
> 
> OK, we could put a comment nearer the top of the file that points the reader 
> further down the file, or we could move the license text into a comment near 
> the top of the file. But usual YANG practice (and I like this) seems to be to 
> prefer to put information into YANG statements rather than into comments.
> 
> Thoughts?
> 
> Thanks,
> William
> 
> > On 9 Jun 2016, at 12:30, William Lupton  wrote:
> > 
> > All,
> > 
> > RFC 6020bis says “The ABNF grammar [RFC5234] [RFC7405] defines the 
> > canonical order. To improve module readability, it is RECOMMENDED that 
> > clauses be entered in this order.”
> > 
> > The ABNF places linkage-stmts (import, include) before meta-stmts 
> > (organization, contact, description, reference) but if there are a lot of 
> > linkage statements (which will be the case in the main module if there are 
> > a large number of submodules… as there are for some of the modules that BBF 
> > is defining) this means that the description can be a fair way down the 
> > module.
> > 
> > Would there be any support for regarding placement of the meta statements 
> > before the linkage statements as not being a violation of canonical order? 
> > Note (this might be inadvertent) that the ABNF actually defines 
> > “meta-stmts” before “linkage-stmts”.
> > 
> > Thanks,
> > William
> 
> ___
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod

-- 
Juergen Schoenwaelder   Jacobs University Bremen gGmbH
Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103 

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

Re: [netmod] Canonical order: linkage and meta

[William Lupton]

All,

No-one replied to this. Fair enough, because it probably seems a rather trivial 
question! But I wanted to point out that a practical consequence of the 
description being a long way down a module is that the license text could 
easily be missed (assuming it’s in the top-level description, which is the 
usual IETF - and BBF - practice). In one BBF module (lots of includes, each of 
which has a revision-date and uses 3 lines), the top-level description begins 
at line 149 out of 204.

OK, we could put a comment nearer the top of the file that points the reader 
further down the file, or we could move the license text into a comment near 
the top of the file. But usual YANG practice (and I like this) seems to be to 
prefer to put information into YANG statements rather than into comments.

Thoughts?

Thanks,
William

> On 9 Jun 2016, at 12:30, William Lupton  wrote:
> 
> All,
> 
> RFC 6020bis says “The ABNF grammar [RFC5234] [RFC7405] defines the canonical 
> order. To improve module readability, it is RECOMMENDED that clauses be 
> entered in this order.”
> 
> The ABNF places linkage-stmts (import, include) before meta-stmts 
> (organization, contact, description, reference) but if there are a lot of 
> linkage statements (which will be the case in the main module if there are a 
> large number of submodules… as there are for some of the modules that BBF is 
> defining) this means that the description can be a fair way down the module.
> 
> Would there be any support for regarding placement of the meta statements 
> before the linkage statements as not being a violation of canonical order? 
> Note (this might be inadvertent) that the ABNF actually defines “meta-stmts” 
> before “linkage-stmts”.
> 
> Thanks,
> William

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod