[Nix-dev] Missing documentation

[Kirill Elagin]

On Mon Feb 16 2015 at 6:22:20 PM Eelco Dolstra <eelco.dolstra at logicblox.com>
wrote:
>
> Note that I removed --help on purpose because I didn't want to maintain
> two sets
> of option documentation. Invoking "man" is also what tools like Git do, so
> it's
> not entirely uncommon.
>
> --
> Eelco Dolstra | LogicBlox, Inc. | http://nixos.org/~eelco/
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev


I remember a recent discussion here regarding nix-1.8’s use of `less` and
`man`, and I should say that I mostly agree with the ones who oppose this
behaviour.

Having short reminders instead of long and verbose man pages is _so much
better_. And having context-sensitive help is _absolutely marvelous_. I
don’t think that git does what you say.

There is a `git help` command that opens a man page indeed, but `git
<command> -h` prints a short summary of options. Other examples include
`iproute2` tools (e.g. `ip help` vs. `ip a help`), `openssl` (`openssl
help` vs. `openssl dh help` [help is not really a special command in this
case, just a thing the tools don’t know what to do with, so they output a
nice short summary]). All of those are just a little bit context sensitive,
i.e. the context is provided only by the first-level command.

NetworkManager is especially awesome as its help is truly conext-sensitive
(`nmcli help` vs. `nmcli c help` vs. `nmcli c up help`).

On the other hand, `systemctl` definitely has room for improvement as it is
not context-sensitive at all, but it still provides a summary instead of
just opening a man page.

What I want to say is that it might be boring to maintain such a
comprehensive help system, but it’s totally worth it, and it’s wonderful
that someone volounteers to do that. BTW it would be nice to have a generic
framework for writing docs and then doing things like generating man-pages
and context-sensitive help automatically. Maybe such a framework already
exists?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20150218/7d970404/attachment.html