Re: [CCAMP] FW: [yang-doctors] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15

[Leeyoung <[e-mail]>]

Diff file attached. 

-----Original Message-----
From: CCAMP [mailto:[e-mail]] On Behalf Of Leeyoung
Sent: Friday, November 16, 2018 11:05 AM
To: [e-mail]
Subject: [CCAMP] FW: [yang-doctors] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15

Hi,

Somehow, I forgot CCAMP as the recipient. 

Thanks.
Young

-----Original Message-----
From: Leeyoung 
Sent: Thursday, November 15, 2018 7:10 PM
To: 'Acee Lindem (acee)' <[e-mail]>; Ladislav Lhotka <[e-mail]>; Martin Bjorklund <[e-mail]>; [e-mail]; [e-mail]
Subject: RE: [yang-doctors] [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15

Hi Acee,

Please see the diff file between version 15 and version 16. I just wanted to check with you if the revision (v16) satisfies you. I believe I did address all of your comments faithfully and corrected all the nits. But in case there are still issues to resolve, please let me know. Thanks.

Best regards,
Young
-----------------------
The followings are my comments to your comments raised during your Yang doctor review. 

Minor Issues: 

      1. The document has 7 authors. This will have to be ok'ed by the 
         responsible AD. 
YL>> now 5 authors in the front page.

      2. There is no consistency in the usage of periods in the YANG descriptions. 

YL>> removed periods in all YANG descriptions. 

      3. The type descriptions in ietf-layer0-types are rather terse and many times
         just repeat part of the leaf name, e.g., "Section.".  Also, optical domain 
         abbreviations are not expanded.

YL>> More words in the type descriptions are supplied; expanded some key terms. 

      4. The indentation in ietf-layer0-types is not consistent. I tried to fix. 

YL>> Fixed. 

      5. When conditions starting with "Augement maximum LSP bandwidth of TE
         link template" and ending with "Augment unreserved bandwidth of TE
         link template" in ietf-layer0-types are commented out.

YL>> Commented-out portions are removed. These augmentation statements are augmenting the topology templates for which there is no network-types attributes. In other words, if you follow the path in the when statement you will not go to an existing leaf in the YANG tree. 

      6. If the model ietf-wson-topology.yang is rendered, the 
         "/* .... */" comments would be better served being in the augmentation
          descriptions rather than in comments. Most of augmentation descriptions
          currently say "WSON label.". 

YL>> All exterior comments are moved to the augmentation descriptions. 

      7. When conditions starting with "Augment label hop of underlay primary path
         of TE link template" and ending "Augment label restrictions end of TE 
         link template" in ietf-wson-topology.yang are
         link template" and ending with "Augment unreserved bandwidth of TE
         link template" in ietf-layer0-types are commented out.

YL>> See my comment for #5.
 
      8. The descriptions at the module level could contain more information than
         just a one liner and the copyright.

YL>> Added more detailed text. 

      7. The "Security Considerations" section in the draft doesn't follow the 
         template in https://trac.ietf.org/trac/ops/wiki/yang-security-guidelines
         and doesn't enummarate the corresponding leaves their delta exposures.
 
YL>> Supplied. 

Nits:

      1. Normally revision description start with the "Initial Version". 

YL>> Corrected. 

      2. Changes references to "Yang" to "YANG".

YL>> Corrected. 

In addition, all nits have been fixed. 



-----Original Message-----
From: Acee Lindem (acee) [mailto:[e-mail]] 
Sent: Wednesday, November 14, 2018 1:44 PM
To: Leeyoung <[e-mail]>; Ladislav Lhotka <[e-mail]>; Martin Bjorklund <[e-mail]>; [e-mail]; [e-mail]
Subject: Re: [yang-doctors] [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15

Hi Young, 

This was merely a follow-up Email on a single comment with the other pruned. Did you miss the Email with the complete review (attached)? 

Thanks,
Aceee

On 11/14/18, 2:33 PM, "Leeyoung" <[e-mail]> wrote:

    Hi Acee,
    
    Thanks for your YANG Doctor's review on draft-ietf-ccamp-wson-yang-15. 
    
    You said:     
    > Acee Lindem <[e-mail]> wrote:
        > >       4. The indentation in ietf-layer0-types is not consistent. I
        > >       tried to fix
    
    I fixed all indentation issues and excessive lines. Here's the updated file attached. Are there any issues with the draft and YANG issues that need to be fixed? 
    
    Thanks.
    Young
    -----Original Message-----
    From: Acee Lindem (acee) [mailto:[e-mail]] 
    Sent: Wednesday, November 14, 2018 6:36 AM
    To: Ladislav Lhotka <[e-mail]>; Martin Bjorklund <[e-mail]>; [e-mail]; [e-mail]
    Subject: Re: [yang-doctors] [CCAMP] Yangdoctors last call review of draft-ietf-ccamp-wson-yang-15
    
    Martin, Lada,
    
    Thanks - this is useful. Many times I've had to fix models lines during xml2rfc iterations. In fact, I wrote a crude python script to print lines in a file exceeding an input length. 
    
    Thanks,
    Acee 
    
    On 11/14/18, 3:55 AM, "Ladislav Lhotka" <[e-mail]> wrote:
    
        On Wed, 2018-11-14 at 09:28 +0100, Martin Bjorklund wrote:
        > Hi,
        > 
        > To YANG doctors in general, and the authors of this draft.
        > 
        > 
        > Acee Lindem <[e-mail]> wrote:
        > >       4. The indentation in ietf-layer0-types is not consistent. I
        > >       tried to fix.
        > 
        > The RFC editor nowadays tries to enforce consistent indentation and
        > style across all YANG modules published in RFCs.  They ask us to help
        > with this by informing authors.  The RFC editor can run tools and
        > manually fix indentation, but since they don't really know YANG, they
        > prefer that the changes they make are minimal.
        > 
        > The recommendation to authors is to run
        > 
        >   $ pyang --ietf --max-line-length 69 <file>
        > 
        > when this is ok run:
        > 
        >   $ pyang -f yang --keep-comments <file> > <outfile>
        
        Another option is to run
        
            $ pyang -f yin -o ymod.yin --keep-comments ymod-orig.yang
        
        and then
        
            $ xsltproc -o ymod.yang yin2yang.xsl ymod.yin
        
        The yin2yang.xsl stylesheet is available here:
        
        https://github.com/llhotka/YANG-I-D/tree/master/.tools/xslt
        
        In my experience, the stylesheet also does a decent job in breaking long lines.
        By default, it tries to break at a space character, another character may be
        suggested by using the "delim" processing instruction.
        
        For example,
        
            <pattern value="..."><?delim )?></pattern>
        
        instructs the stylesheet to break the argument after a right parenthesis.
        
        Lada
        
        > 
        > Unfortunately, the tool isn't 100% perfect, in that it won't ensure
        > that all lines are short enough.  Specifically, the argument to "path"
        > gets printed on a single line.
        > 
        > So the recommendation is to run this tool, and then manually tweak the
        > long statements, e.g. run
        > 
        >    $ diff <oldfile> <newfile>
        > 
        > to find the diffs.
        > 
        > 
        > 
        > /martin
        > 
        > _______________________________________________
        > yang-doctors mailing list
        > [e-mail]
        > https://www.ietf.org/mailman/listinfo/yang-doctors
        -- 
        Ladislav Lhotka
        Head, CZ.NIC Labs
        PGP Key ID: 0xB8F92B08A9F76C67
        
        
    
    

_______________________________________________
CCAMP mailing list
[e-mail]
https://www.ietf.org/mailman/listinfo/ccamp