Re: [bug-inetutils] [SCM] GNU Inetutils branch, master, updated. inetutils-1_9_1-224-gf88d586

[Alfred M. Szmidt]

   >    address@hidden
   >    +where @var{name} is the name to be used by the running host.
   >    +
   >    address@hidden Command line options
   >    address@hidden options}
   > 
   > I actually changed this so that there wouldn't be a seperate section
   > for the options -- or a synopsis; since that is how it is done in
   > coreutils.  Could you explain your rationale?  I know that there where
   > a few places that still had the Synopsis stuff left, but that was a
   > bug.

   That might be acceptable for simple utilities with only a need to describe
   their command line options, like the executables of Coreutils do.
   But then come our Ttp, Telnet, and Ping, carrying a lot of information
   in addition to command line options. They need a menu of entry points
   quickly, not after skipping some one hundred lines of text!

While some things do carry a lot of information, I think most of the
tools are quite trivial option wise -- at least compared with things
in coreutils which have far more options than we do.  What about doing
it for the complicated cases (ping for example, while telnet is quite
simple option-wise)?  hostname is a good example of a very very simple
command without many options.

So for hostname/telnet/... we have the following structure,

        @node PROGRAM invocation
        @chapter @command{PROGRAM}: Do something or other
        @cindex PROGRAM
        
        @command{PROGRAM} is a program to do something or other.
        
        @example
        PROGRAM address@hidden@dots{}]
        @end example
        
        @table @option
        @item --smurf
        List all smurfs.
        
        ...
        @end table

And for ping, ifconfig, and what not,

        @node PROGRAM invocation
        @chapter @command{PROGRAM}: Do something or other
        @cindex PROGRAM
        
        @command{PROGRAM} is a program to do something or other.
        
        @example
        PROGRAM address@hidden@dots{}]
        @end example

        @menu
        * General options in PROGRAM::      Options which affect general 
program behavior.
        * ICMP control options::            Options affecting ICMP packets.
        ...
        @end menu


Though having looked over ping, I'm not convinced that such a
complicated split is warrented now.  But I would be OK with this type
of structuring than having lots and lots of pointless sections.

What is complicated with ftp, telnet, etc is the interactive part --
not the actual options.

   >    +The TCP/IP specification states that the @acronym{TTL} field
   >    +of a new @acronym{TCP} packet should be set to 60,
   >    +but many systems use smaller values (4.3BSD uses 30
   >    +and 4.2BSD used 15).
   > 
   > Uses? Maybe used?  I don't know any running 4.2 or 4.3 BSD's ...

   That is verbatim from the previous text, just a new linebreak.
   These verbatim tenses are still present in the manual page
   ping(8) delivered in FreeBSD 9.0 to this very day!

Ah, ok.

   >    +Some BSD variants offer a kernel setting to inhibit all replies
   >    +to ICMP_MASKREQ packets.
   >    +This setting can detected using
   >    +
   >    address@hidden
   >    +$ sysctl net.inet.icmp.maskrepl
   >    +net.inet.icmp.maskrepl: 0
   >    address@hidden example
   > 
   > I think we should not mention specific means of changing ICMP MASKREQ;
   > just saying that it can be done is enough I think.  What do you think?

   I wrote it in order that the reader understand why some systems do reply
   with a netmask, while others disregard the request by construction,
   yet others do so because a tentative decision of their administrator.

Then I think it would be better to just explain that this can be the
case, without an explicit example.

   > Also, FreeBSD is not 100% free software so it is better to not mention
   > it.

   Irrelevant and certainly a matter of opinion.  Think of GDFL!

It is relevant for our documentation since we try hard to not refer to
non-free operating systems or non-free software.

   The naming conventions of section and nodes are very unclear to me,
   so I would appreciate some pointers.  I will leave synopses and the
   like for further discussion, but will now revert @kbd and @acronym
   and the above trivia.

What do you find unclear about them?