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:

26 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:

1 Like
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
9

Thanks, yes, I spent roughly 2002 - 2006 using Emacs and attempting to enjoy it. This followed immediately after using vi from 1994-2001, and afterwards I went back to vi and have used various dialects of it ever since (with a couple brief detours into GUI editors). I gave it a fair chance, more than fair really, and it isn’t shaped like my brain. There are reasons that different people prefer different things in an editor. I am glad that people who like Emacs get to use it, but not everybody is a convert-in-waiting.

2 Likes
10

The most basic problem with the command line info program is that everyone within GNU who actually likes Texinfo-format documentation is a diehard Emacs user. So Emacs’ built-in reader for that format, info-mode, is reasonably good; but what they wrote, as a standalone reader utility, when they eventually accepted that they couldn’t persuade everyone to switch to Emacs, was a flimsy knockoff of info-mode. That’s why the keybindings are so weird, and why it has never worked very well.

(N.B. I am a diehard Emacs user and I actually find it easier for most purposes to read the HTML versions of the GNU manuals than to use either. There’s things info-mode can do more easily, like full-text search, but the web-browser UI has had so much more polish overall.)

It is also the case that many of the existing Texinfo-format manuals are decades out of date and/or were written as guides rather than reference manuals; this is why, for instance, the glibc manual doesn’t document pthreads at all, and the tar manual makes you hunt for the options you want. The FSF used to fund professional technical writers to work on their manuals. I don’t know why they stopped.

3 Likes