Dear Alfred,
onsdag den 5 februari 2014 klockan 06:29 skrev Alfred M. Szmidt detta:
> Hello,
>
> I started some days/years ago to rewrite the manual; reorganize it a
> bit, and such. Here is a work in progress; what do people think?
I like the consistent addition of synopses. (pftp needed help though!)
> There are a few chapters missing; but I've gone over the options for
> each command, and added any missing things. I'd like to write a
> chapter on Shishi/Kerberos support, IPv6 support and ammend the
> ifconfig part properly when I get some spare time.
I have separated the generic options of ifconfig from the few system
specific options in a patch on top of your suggestion. Observe also
that I reordered the options to "-B, -b, --brdaddr, --broadcast"
and "-d, -p, --dstaddr, --peer", in that order, to name the short
switches first.
The functionality for "pointopoint" is probably unknown to us,
whether it works on BSD and Solaris, so it is mentioned as
specific to GNU/Linux.
> Basically, I'd like some input on if people have any good suggestions
> in imporving the manual, and if the layout in this copy is "good".
Personally, I am convinced that "See also" should be used throughout
the manual, not the present "Also see". The folding of text into the
macro "kerberos" is a clear gain. To sum up, I am happy that you are
taking command in performing a rewrite.
Best regards,
Mats E A
diff --git a/doc/inetutils.texi b/doc/inetutils.texi
index f69be86..ab0fe78 100644
--- a/doc/inetutils.texi
+++ b/doc/inetutils.texi
@@ -6,7 +6,7 @@
@include version.texi
-@c Macros used through out the manul.
+@c Macros used throughout the manual.
@macro synopsis{command}
@noindent
Synopsis:
@@ -265,18 +265,18 @@ NIS/YP domain name.
There are no command specific options.
@node hostname invocation
-@chapter @command{hostname}: Show or set system host name.
+@chapter @command{hostname}: Show or set the system's host name.
@pindex hostname
-@command{hostname} is a program to show or to set the name of a host
+@command{hostname} is a program to show, or to set the name of a host
system.
@synopsis{hostname [@var{option}@dots{}] [@var{name}]}
@noindent
-where @var{name} is the name to be used by the running host.
+where @var{name} is the name to be assigned to the running host.
-The program accepts the following options. Also see @ref{Common
+The program accepts the following options. See also @ref{Common
options}.
@table @option
@@ -342,28 +342,10 @@ Get NIS/YP domain name.
@node Generic invocation
@section Generic invocation
-@node Invocation on GNU/Linux
-@section Invocation on GNU/Linux
-
-@synopsis{ifconfig [@var{option}@dots{}] @var{name} [@var{addr}]@*
-@ @ @ @ [broadcast @var{brdaddr}]@*
-@ @ @ @ [pointopoint|dstaddr @var{dstaddr}]@*
-@ @ @ @ [netmask @var{mask}]@*
-@ @ @ @ [metric @var{n}]@*
-@ @ @ @ [mtu @var{n}]@*
-@ @ @ @ [txqueuelen @var{n}]@*
-@ @ @ @ [up|down] [@var{flags}]}
-
-The program accepts the following options on GNU/Linux. Also see
+The program accepts the following generic options. See also
@ref{Common options}.
@table @option
-@item -T @var{n}
-@itemx --txqlen=@var{n}
-@opindex -T
-@opindex --txqlen
-Set transmit queue length to @var{n}.
-
@item -a
@itemx --all
@opindex -a
@@ -377,39 +359,30 @@ Display all available interfaces.
Set interface address to @var{addr}.
@item -B @var{addr}
+@itemx -b @var{addr}
@itemx --brdaddr=@var{addr}
@itemx --broadcast=@var{addr}
-@itemx -b @var{addr}
@opindex -B
+@opindex -b
@opindex --brdaddr
@opindex --broadcast
-@opindex -b
Set broadcast address to @var{addr}.
-@item -d @var{addr}
-@itemx --dstaddr=@var{addr}
-@itemx --peer=@var{addr}
-@itemx -p @var{addr}
-@opindex -d
-@opindex --dstaddr
-@opindex --peer
-@opindex -p
-Set destination (peer) address to @var{addr}.
-
@item --down
@opindex --down
Shut the interface down.
-@item --format=@var{format}
-@opindex --format
-Select output format; set to @samp{help} for info.
-
@item -F @var{flag}[,@var{flag}@dots{}]
@itemx --flags=@var{flag}[,@var{flag}@dots{}]
@opindex -F
@opindex --flags
Set interface flags.
+@item --format=@var{format}
+@opindex --format
+Select output format; set @var{format} to @samp{help} for
+available formats.
+
@item -i @var{name}
@itemx --interface=@var{name}
@opindex -i
@@ -452,7 +425,43 @@ Activate the interface (default if address is given).
@itemx --verbose
@opindex -v
@opindex --verbose
-Output information when configuring interface.
+Output information when configuring an interface.
+
+@end table
+
+@node Invocation on GNU/Linux
+@section Invocation on GNU/Linux
+
+@synopsis{ifconfig [@var{option}@dots{}] @var{name} [@var{addr}]@*
+@ @ @ @ [broadcast @var{brdaddr}]@*
+@ @ @ @ [pointopoint|dstaddr @var{dstaddr}]@*
+@ @ @ @ [netmask @var{mask}]@*
+@ @ @ @ [metric @var{n}]@*
+@ @ @ @ [mtu @var{n}]@*
+@ @ @ @ [txqueuelen @var{n}]@*
+@ @ @ @ [up|down] [@var{flags}]}
+
+The program accepts the following additional options on GNU/Linux.
+See also @ref{Common options} and the previous section on generic
+invocation.
+
+@table @option
+@item -d @var{addr}
+@itemx -p @var{addr}
+@itemx --dstaddr=@var{addr}
+@itemx --peer=@var{addr}
+@opindex -d
+@opindex -p
+@opindex --dstaddr
+@opindex --peer
+Set destination (peer) address to @var{addr}.
+
+@item -T @var{n}
+@itemx --txqlen=@var{n}
+@opindex -T
+@opindex --txqlen
+Set transmit queue length to @var{n}.
+
@end table
@node Invocation on BSD
@@ -465,8 +474,8 @@ Output information when configuring interface.
@ @ @ @ [mtu @var{n}]@*
@ @ @ @ [up|down]}
-The program accepts the following options on BSD. Also see
-@ref{Common options}.
+The program accepts no BSD specific options. See the generic
+invocation and the @ref{Common options}.
@node Invocation on QNX
@section Invocation on QNX
@@ -481,8 +490,8 @@ The program accepts the following options on BSD. Also see
@ @ @ @ [mtu @var{n}]@*
@ @ @ @ [up|down]}
-The program accepts the following options on Solaris. Also see
-@ref{Common options}.
+The program accepts no Solaris specific options. See the generic
+invocation and the @ref{Common options}.
@node logger invocation
@chapter @command{logger}: Send messages to system log.
@@ -497,7 +506,7 @@ Library Reference Manual}.
The options are followed by the message which should be written to the
system log. If not specified, and the @option{-f} flag is not
-provided, standard input will be used..
+provided, standard input will be used.
The program accepts the following options. Also see @ref{Common
options}.
@@ -516,7 +525,7 @@ is to use whatever IP version that matches the host.
@opindex --ipv6
Use IPv6 as transport when logging to a host. The option is present
also on systems without support for IPv6, but will then issue a
-warning and then fall back to IPv4 when delivering the message.
+warning and fall back to IPv4 when delivering the message.
Both options are most influencial when the target host is named using
a symbolic name, but numerical addresses for host or source must also
@@ -1314,8 +1323,8 @@ Commands can either be entered interactively, or piped as a batched
job read from standard input. @command{ftp} is able to distinguish
between these two modes of operation.
-@synopsis{ftp [@var{option}@dots{}] [@var{host} [@var{port}]]@* pftp
-[@var{option}@dots{}] [@var{host} [@var{port}]]}
+@synopsis{ftp [@var{option}@dots{}] [@var{host} [@var{port}]]@*
+pftp [@var{option}@dots{}] [@var{host} [@var{port}]]}
@noindent
The alternate name @command{pftp} starts @command{ftp} in passive
