[Nix-dev] Missing documentation

[Mikey Ariel]

On 16 Feb 2015, at 17:04, Ertugrul Söylemez <ertesx at gmx.de> 
> 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."
> 
I wouldn't be in such a hurry to document things in this manner , because the basic assumption is "if it's documented then it's supported and we welcome users to use it", and how would you differentiate between regular and advanced users anyway? 

Of course you should introduce the feature or functionality with the use-case that it's aimed at (i.e. Why do I need this?), but documenting something and then disclaimering it with "but actually you don't really want to use this coz it's risky" is usually just an invitation for mayhem. 

Bottom line IMHO - either you educate users with the correct information and then trust them to use the feature responsibly, or you don't expose 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.
> 
> 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.
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev