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

[Mats Erik Andersson]

fredag den 14 december 2012 klockan 10:39 skrev Alfred M. Szmidt detta:
>    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!

Observing this (and that most text parts are legacy from last century,
common with FreeBSD and OpenSolaris) and keeping consistent with myself,
I fell into the trap of putting synopses sections for the clients,
until the textual changes for Ftp got so large I had to limit my
amount of versioned commit.

>    -number of IP routers that the packet can go through before being
>    -thrown away.  In current practice you can expect each router in the
>    -Internet to decrement the TTL field by exactly one.
>    +The @acronym{TTL} field, @dfn{Time To Live}, of an @acronym{IP}
> 
> @acronym is discouraged; though I don't mind it but it breaks `make
> syntax-check'.  See:
> http://lists.gnu.org/archive/html/bug-gnulib/2010-03/msg00321.html

Fair enough!

> 
>    +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!

> 
>    +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.

> 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!

>     specified, show status of @var{file-name} on remote machine.
> 
>    address@hidden rename address@hidden address@hidden
>    -Rename the file from on the remote machine, to the file to.
>    address@hidden rename address@hidden address@hidden
> 
> One ] to much or to little :-)

Right, a mix-up of other passages with "say [this [and that]]".

> 
>     @item
>    -If the first character of the file name is @samp{|}, the remainder of
>    +If the first character of the file name is @kbd{|}, the remainder of
> 
> I think @samp is correct here -- or @code, @kbd is for actual input by
> the user.

The user is in fact giving '|' as part of an input string,
but I believe to see your distinction here.

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.

Regards,
  Mats E A