[Nix-dev] Missing documentation

[Eelco Dolstra]

Hi,

On 16/02/15 16:02, Ertugrul Söylemez wrote:

>>>> +1 to doc fixes! :-) I'll gladly help with peer review for the
>>>> content or whatever I can within the prose capacity :-)
>>>
>>> Nobody else?  I would just do it, but at the very least I need an
>>> explanation of the missing parts.
>>
>> The best way to find out might be to use git blame and see commit
>> history.
> 
> Okay, I will try that.

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 :-)

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.

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

-- 
Eelco Dolstra | LogicBlox, Inc. | http://nixos.org/~eelco/