> 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!)
Thanks, pftp got eaten by to much paragraph filling...
> 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.
Thanks!
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.
No idea; would be nice to know if it works. You think you could check
if it does?
One thing I do want to see to is that anything that our commands
accept is documented; even if the functionality might not work -- that
or outright remove the `untested' feature completley until someone
implements and tests it.
> 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".
Agreed; though I would go further and say that we should use @xref
where possible. E.g. instead of,
| The program accepts the following options. See also @ref{Common
| options}.
we can write,
| The program accepts the following options. @xref{Common options}.
I'll incoperate your changes into my stuff; and continue doing more
polishing. When I have something that is at least as "good" as the
current manual (there are a few sections that I totally ripped out),
I'll push it.
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.
Can you think of any other places where we could macro-fy things like
this?
I was maybe thinking about grouping the IPv6 specific switch under one
macro, IPv4 under another -- but then I decided that this was to much.
For example,
@item -4
@itemx --ipv4
@opindex -4
@opindex --ipv4
Use IPv4 as transport when logging to a host. The default behaviour
is to use whatever IP version that matches the host.
could be one macro, @opt_ipv4 or whatever.
Cheerio...
