bug-inetutils
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [bug-inetutils] Manual rewrite ..


From: Alfred M. Szmidt
Subject: Re: [bug-inetutils] Manual rewrite ..
Date: Wed, 12 Feb 2014 12:14:36 -0500

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



reply via email to

[Prev in Thread] Current Thread [Next in Thread]