[Nix-dev] Missing documentation

[Ertugrul Söylemez]

> Regarding --register-validity, it's a bit of internal command that I'm
> not sure should be documented. But yeah, ‘exportReferencesGraph’
> shouldn't refer to it :-)

Well, it is apparently a helpful utility when you change core parts of
NixOS, when you create your own Nix-based distribution or when you
create virtual machine images without using NixOS tools.  In fact it may
be the only way to do it properly.

I believe everything should be documented at least in a technical
manual.  But there is nothing wrong with putting a note there:  "Regular
users should not need to use this command."


> The format is as follows (see decodeValidPathInfo() in store-api.cc):
>
>   <line containing the store path>
>   <if --hash-given is used, a line containing the hash of the contents of
>    the path (nix-store -q --path)>
>   <if --hash-given is used, a line containing the size of the contents of
>    the path (nix-store -q --size)>
>   <the deriver>
>   <an integer containing the number of references>
>   <the references, one per line>
>
> This is repeated until EOF.
>
> See pkgs/build-support/kernel/paths-from-graph.pl for an example of a
> script that generates registration info in this format.

Thanks.  That's a bit difficult for shell scripts to parse, because it's
context-sensitive.  Is there a context-free or regular format or a
predefined parser that I can use from within a small shell script?  I
need to copy the full closure of a derivation in a builder.


>> Regarding the overhaul of `--help` I will just do it and see what
>> people think about it.
>
> 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.

One advantage of the way Git does it is that it's context-sensitive.  It
does not just fire up a general man-page and lets you search it.  Nix
tools have a large and growing set of options, so at least we should
have that.

Would you agree to reintroduce it, if it contributes to a better UX?  I
will think of ways to keep everything in one place.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 472 bytes
Desc: not available
Url : http://lists.science.uu.nl/pipermail/nix-dev/attachments/20150216/6ef5af69/attachment-0001.bin