Accessible documentation

[oxij]

Goals:

• All the docs to be available (in /nix/store), accessible (with standard tools) and discoverable (in deterministic locations) locally.
• All packages having their man page built when possible.
• NixOS documentation to be available in info format.
• (wishful thinking) To have a thing that indexes all the man, info and haddock pages for full text search using e.g. Xapian lib.

This issue exist to list current issues, ideas and progress in that pursuit of said goals.

[1] Mail-list thread http://lists.science.uu.nl/pipermail/nix-dev/2015-December/018844.html
[2] Related mail-list subthread http://lists.science.uu.nl/pipermail/nix-dev/2015-November/018740.html

[oxij]

On a second though, I decided to split the first to into separate issues #11500 and #11501.

[vcunat]

NixOS documentation to be available in info format.

Most of our docs are in DocBook, so there should be plenty of semantic information to get a reasonable *.info output by direct conversion.

Local "docs-google" would be nice indeed. Perhaps some distro has already paved a way? IMHO people tend to use the web search engines mainly because it's an extremely simple way to get good results.

[oxij]

Vladimír Čunát notifications@github.com writes:

Most of our docs are in DocBook, so there should be plenty of semantic information to get a reasonable *.info output by direct conversion.

Yep, I hope to get into that in January.

Local "docs-google" would be nice indeed. Perhaps some distro has already paved a way? IMHO people tend to use the web search engines mainly because it's an extremely simple way to get good results.

Regrettably, I'm not aware of a really awesome solution. Closest thing
I'm currently aware of is recoll, but it seems to GUI for my tastes. I
didn't play with it enough yet, however, and since helm-recoll exists
it just might prove to have a good CLI support. Personally, I'd like to
have something like hoogle.

[larkery]

I have been thinking about this with respect to my user profile (I don't tend to install lots of packages into the system profile); at the moment to get an info dir for these packages and to have a working apropos I have some horrible scripts which generate the relevant indexes for my profile into some custom directories.

What I am wondering is (and maybe someone here will have a view?) whether there is any way to persuade nix-env to do this, by (say) adding a post-build hook for the user's environment which does this job.

It seems like quite a common thing to want to be able to do: generate a user (or system) profile, and then build an index of all the things that went into it.

[vcunat]

nix-env currently doesn't have a mechanism to add such hooks.

[larkery]

I just had a poke around in the source and see that it would require changes to nix and hence a global rebuild, which is not on the cards for me to consider today.

However, for any other interested readers, the buildEnv in nixpkgs does have this facility, via postBuild, and the comment at the top claims it will one day be merged back into nix.

It seems that a user-level solution will then be to package up a few commands for generating indexes (e.g. for texinfo), and then to glue them to user environments built with pkgs.buildEnv using the postBuild argument. This does prevent use of nix-env for convenient installation at the shell; I guess I could define my own nix-env which edits a derivation for me to achieve same efect.

I do not know about the system profile equivalent.

[larkery]

Hah, further source reading suggests that this will still not work, specifically for texinfo, because the basic nix-env builder will filter out whatever dir file the postBuild hook creates. Sad face.

[vcunat]

In any case, I believe nix-env doesn't provide a way to pass parameters to the buildEnv it calls.

[larkery]

So for future reference,

       postBuild = ''
       for infofile in "$out/share/info/"*.info*; do
          ${pkgs.texinfo}/bin/install-info "$infofile" "$out/share/info/dir2"
       done
       '';

works, but generating the texinfo index into $out/share/info/dir does not because the more fundamental nix-env script corepkgs/buildenv.pl will not link anything whose path ends with info/dir/

[oxij]

Related to #38114.

[stale]

Thank you for your contributions.

This has been automatically marked as stale because it has had no activity for 180 days.

If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.

Here are suggestions that might help resolve this more quickly:

1. Search for maintainers and people that previously touched the related code and @ mention them in a comment.
2. Ask on the NixOS Discourse.
3. Ask on the #nixos channel on irc.freenode.net.