Plan 9 from Bell Labs’s /usr/web/sources/patch/applied/man1-sync1/notes

Copyright © 2021 Plan 9 Foundation.
Distributed under the MIT License.
Download the Plan 9 distribution.


Sat Dec 10 11:36:07 EST 2005 rsc
    Not all of my comments about man1-sync0 were addressed.
    I applied the changes and then made my own fixes.
    Please diff the current pages against what you submitted
    to see what I changed.
    
    Some comments:
    
     - There were still ".BI onearg" lines in the edited
       lines you submitted.
     - You don't seem to like the [this | that] syntax,
       but it's okay (and useful!).  It means you can 
       specify one or the other but not both.  You dropped
       it in the acme usage and in the awk usage.
     - There are no spaces around brackets in the 
       usage strings printed by programs.  
     - The acme(4) page you started with appears to have
       been out-of-date, since you removed the menu and
       nomenu ctl messages in the patch.
       Please make sure you're up to date, and after 
       creating a patch, run patch/diff your-patch and
       look through the diffs just to double-check that
       they're what you expected.
     - There were still multiple instances where you 
       changed the usage message but did not update
       the text to reflect new names.  This happened in
       both acme(1) and awk(1).  If you change the names
       in the SYNOPSIS, make sure you update the text.
     - I named the -l option to acid "library" rather than
       "module".  The man page used "library" a lot more
       than module (used only once).  Don't blindly follow
       what the program prints for a usage message.  Often
       the documentation has better names.  The fact that
       you had to rename a whole subsubsection of the manual
       was my tip-off that I should just leave the name as
       it was.
     - When you document a new option or argument,
       make sure you get all its effects.  It turns out that
       awk's -safe does more than just disable ENVIRON.
    
    Thanks for going through these.  I really appreciate it.
    The above comments are very small things, but all in
    all I'm very happy to see these getting checked and fixed.
    
    Russ
    


Bell Labs OSI certified Powered by Plan 9

(Return to Plan 9 Home Page)

Copyright © 2021 Plan 9 Foundation. All Rights Reserved.
Comments to [email protected].