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

[Leeyoung <[e-mail]>]

Hi Acee,

Thanks for your quick reply and pointing out specific acronyms to be expanded. I agree with you on the expansion of the acronyms, which is incorporated in the proposed revision (v16). Please see the attached diff file that compares v15 and v16. I will upload version 16 shortly. Please let me know if there are still issues to be corrected. 

Thanks & Best regards,
Young

-----Original Message-----
From: Acee Lindem (acee) [mailto:[e-mail]] 
Sent: Saturday, November 17, 2018 11:45 AM
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, 

The changes look good. The one question I have is whether you should expand the optical acronyms on first use in the ietf-layer0-types.yang. Even if they are defined in other documents, the models need to stand on their own. I guess the question is whether anyone using types in the first place would know all these acronyms. I'm talking about TP, TTP, PID, OADW, ROADM, CWDM, DWDM, FEC, G-FEC, E-FEC, ODU, OPU, OTU, OXC, and potentially others. I'll leave it up to you. 

Thanks,
Acee

On 11/15/18, 8:22 PM, "Leeyoung" <[e-mail]> wrote:

    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