[Nix-dev] How to convert non string options to documentation String ?

[Nicolas Pierron]

On Mon, Mar 9, 2009 at 11:42, Marc Weber <marco-oweber at gmx.de> wrote:
>    bootWays = mkOption {
>        default = [config.boot.ways.grub];
>        # proposal: use somehting like this instead:
>        # default = mkDocumentedVal [config.boot.ways.grub] "[config.boot.ways.grub]"
>        description = "
>          ...
>        ";
>      };
>
> However we need a way to define a user readable descrription of that default..
> One generic way to do this would be adding an indirection:
>
> mkDocumentedVal = val ; documentation : {
>  inherit val documentation;
>  _type = "documented_val";
> }
>
> valFromDocumentedVal = x :
>  if typeOf x == "documented_val"
>    then x.val
>    else x
>
> or such. I think you get the idea.

So the idea is to have a nice abstraction inside default option
values.  This problem arise when you have options like
boot.kernelPackages where you may want to have
"pkgs.kernelPackages_2_6_25" instead of ... (cf
http://nicolas.b.pierron.free.fr/nixos/manual.html).

For documentation purpose, the evaluation of the example and of the
default value is a bad thing because this add extra complexity which
should not be shown because of the following reasons:
- have an understandable documentation.
- keep the documation simple.
- not tempting the user to hack.

So I agree that we need something cleaner in the documentation.

> Is there already a another (maybe easier solution?)

Many solutions exist for this problem:

- The best one would be to implement a prim-op to keep the original
code (with a relative identation) almost as your are doing except that
we don't have to write the same code twice which is evaluated by
default except if it is the argument of another primop

default = ~keepDoc~ [ config.boot.ways.grub ];

getDoc opt.default

- Add a defaultPP attribute which contains the string version of the
value.  Then:

if opt ? defaultPP then opt.defaultPP else opt.default

I suggest you to use the defaultPP solution because adding extra
function before the value of the default attribute could be
missleading (IMO).

-- 
Nicolas Pierron
http://www.linkedin.com/in/nicolasbpierron
- If you are doing something twice then you should try to do it once.