Some manpage-related stuff you might want to turn on

Guides
1

This is one of those things that Unix newcomers in particular would probably benefit from, but not know to ask for. I posted about it originally over on the fediverse, but when I saw this category I realized it belongs here.

{ pkgs, ... }:

{
  environment.systemPackages = [ pkgs.man-pages ];

  documentation = {
    dev.enable = true;
    man.generateCaches = true;
    nixos.includeAllModules = true;                                         
  };
}

There’s a bunch of related options under documentation.* that you can and should look up; I left out everything that defaults to on.

There are good reasons that these default to off - they use more disk space, and rebuilds take a bit longer - but for a machine that you use interactively it’s well worth it.

The man-pages package is easy to miss, because most programs install their own manpages regardless, so this package just has some very general system-wide stuff. You want that stuff, though! In my view, the importance of man intro as a way to welcome first-timers can’t be overstated.

The generateCaches option is needed to make the apropos and whatis commands work properly. Again, one of those things where the people most in need of it may not even realize it’s supposed to work.

The rest of this is just about turning on docs for a few more things, on the principle that it’s better to have it whether or not you need it.

Another thing you can and should do is type nixos-help and see if you’re satisfied with what it does. It should open the NixOS manual in a browser - which one will depend on a lot of stuff. If you’re not, you may need to set $BROWSER in your shell config. If you want it to ignore the GUI and work entirely in a terminal, install w3m and set BROWSER=w3m. I realize it may be a bit quixotic of me to imagine that anyone younger than me wants that, but hey. :slight_smile:

20 Likes
2

Do you know if there is an info equivalent?

3

the only option under documentation.info is documentation.info.enable, and it defaults to true, so no action needed.

I don’t think info has an index that needs to be rebuilt in the same way man does, but I have never managed to form a close emotional connection with the info system (the keybindings have confused me every time I’ve tried, for thirty years now), so I’m not totally sure

is that what you were asking?

4

looking through all-packages.nix it does look like there’s things like glibcInfo which people might want to install. there’s also a couple specialized packages of manpages that we’re not fully sure of the contents of. taking inventory of all this and making recommendations about it might be an interesting project for somebody (I might do it at some point but I dunno when I’ll have time).

5

the only option under documentation.info is documentation.info.enable, and it defaults to true, so no action needed.

Yes, thank you!

I have never managed to form a close emotional connection with the info system (the keybindings have confused me every time I’ve tried, for thirty years now), so I’m not totally sure

Within emacs if you get used to it it’s much nicer than man pages because of the hierarchy and it’s ability to explain things I think.

Not sure if this is relevant, but I always link these videos when someone brings up not being fond of emacs info manuals:

May not change anything for you, but for me it made my computing experience much nicer :slight_smile:

6

Yes, this looks like a good idea. Thank you.

7

Thanks for this! I had discovered documentation.dev.enable a few years ago, but had consigned myself to man -K instead of man -k/apropos since I didn’t know about documentation.man.generateCaches (or maybe it didn’t exist in 2019?). Yay!

8

very welcome! yeah, I don’t know the history of the generateCaches option, but it always bothered me that apropos doesn’t work out of the box, since it was a big part of how I learned Unix in the first place back in the 90s. anyway, today it exists :slight_smile:

1 Like