[Nix-dev] Re: NixOS manual: "declared by" & "defined by"

[Nicolas Pierron]

On Wed, Sep 16, 2009 at 13:02, Eelco Dolstra <e.dolstra at tudelft.nl> wrote:
> Hi,
>
> Ludovic Courtès wrote:
>
>> I’m not sure about the command name, but yes, that’d nice.  A ‘--manual’
>> option as Marc suggests would be nice too.
>
> Maybe we don't need a --manual, "man nixos" would be more logical.  There
> already is a configuration.nix manpage, we just need to add some more manpages
> (including one for nixos-rebuild).

Indeed, extending the configuration.nix man page can be the first step.

>>> I've made some modification to my manual generation which provide this
>>> information (see http://nbp.name/nixos/manual.html ).
>
> Just one question for Nicolas: do the "Defined by" paths include disabled values
> (i.e. those under a "mkIf false ...")?

Yes it does, as well as the values which are override.  The reason is
that properties are delayed, and "mkIf false" is moved to each
definition before its evaluation.

> And a suggestion: we could hyperlink the filenames to the module sources, either
> under file:///etc/nixos or in the SVN repo.

This would be excellent to have a link to the subversion repository
from the manual page.

>> Some nitpicking:
>>
>>   * Could you remove ‘/trace/nixos’ from paths?

I think this could be removed, I have to check the content of the
"modulePath" variable before.

>>   * Could you remove the “defined by” line when it’s the empty list?

Of course.

>>   * I’d prefer “used by” instead of “defined by”, and maybe even
>>     “defined by” instead of “declared by”.

Just a few examples of the current vocabulary ;)

* I declare:

{
  options = {
     foo = mkOption { ...};
  };
}

* I define:

{
  config = {
     foo = 42;
  };
}

* I use: (not reported)

{config, ...}:

let
  bar = config.foo;
in
  ...

-- 
Nicolas Pierron
http://www.linkedin.com/in/nicolasbpierron
Lars Rasmussen (Google IO 2009) - Icland is an icland.