This guidance on man pages for the GNU project is wild

The thing is—GNU is right here, that info is better. You can run info from the command-line just like man, except info pages are hierarchical, indexed, and have links. The same sources can then be used to generate web pages. You then have one set of docs you update, which are accessible both from the web and from the terminal. The system can handle large projects and it’s easy to navigate—much easier than man. It’s beautiful.

Man, by comparison, gives you individual pages. I think that’s great when you need to stare at the docs for an individual API call for a while, like when you read “man mmap” or something, but it sucks for large projects. You can convert man pages to web pages but it’s not competitive with info.

Try running “info gcc” or “info make” at some point and you’ll see something beautiful. You can browse linearly using space/backspace, and Q to quit. You can do a text search across the whole manual, you can follow links, etc.

I find this system good enough that when it’s available, I don’t use the web browser to look up docs for stuff like GCC or Make.

> I literally did not know info pages existed for the first 15 years I used GNU tools, and I've still never used one

A bit of irony: the link and screenshot in the OP are from the HTML version of an Info manual! In my book, that counts as using one :). HTML Info manuals are right up there with Stack Overflow for most queries about GNU tools. Most people who have searched the web for how to do something with Make, GCC, or tar have used an Info manual, unwittingly or otherwise. There are even two types of HTML export¹: one web page per node, good for sharing links, and everything on one page, good for lazy full-text search.

And while the TUI program is indeed pretty niche these days (probably partly due to the fact that it’s not installed by default in many environments), any Emacs user worth their salt is intimately familiar with Info-mode :D

1: https://www.gnu.org/prep/standards/

I can say with confidence that the language used for Info documentation is vastly superior to the nroff/troff language. Man pages are not suitable for writing large manuals. It didn't stop me, but what I'm doing is not really scalable.

To get a decent HTML version I had to maintain my own fork of the man2html program (a particular one of them; there exist more than one, and all suck in different ways). That program is not enough; there is considerable custom post-processing done on the HTML output, to add a bettr table of contents and internal hyperlinks and such.

I wrote numerous macros for all the necessary markup needed in a manual. The macros have weird syntax. I wrote a lint tool to check the 95,000+ line document for errors in the uses of these macros, which frequently occur.

I also wrote a minor tool which I use as a filter in CGIT which renders man pages. (It's not used for that one; that's too large and complex.) E.g. if you look at this small page, you can see it in action:

https://www.kylheku.com/cgit/cppawk/tree/cppawk.1

you see it as if you were reading it in man, rather than the source code, which you can see in the "plain" view. The line numbers are wrong: they are calculated from the original source. So while the rendered page ends at 250-something lines, the line numbers keep going past 400. There is no way a CGIT filter can indicate that it has completely munged the input into a different form, which has fewer lines.

So the summary of man pages is: awful language + next to nonexistent tooling for publishing quality documents in multiple formats.

On the topic of troff, it's the GNU project which holds up that language: it provides a program called GNU Roff (groff). If you ever render a man page to PDF, that's likely what you will be using. So, in a way, GNU is committed to the troff language as much as to Info.

But GNU projects would be crazy to switch from Info to man; it's an unthinkable regression.

Use 's' for search (or '/').

Try 'm' for menu,'i' for index, or 'g' for go-to node. 't' for top.

Info manuals are like HTML websites except actually navigable. No menu on the left that contains 10,000 hits for the search term. It's paginated, yet searchable across pages. Well written Info docs (anything core GNU) are indexed so that pressing 'i' usually gets you there.

For example, ever try to find something in the Python docs? Almost impossible and the HTML search is useless. Using Info format, you can bind together related information that's spread across separate parts of the documentation. And that's using a converted version, not something intended for Info. (Sphinx has Info as an output option.)

It feels like people's reactions to Info is often, "I don't know this, therefore it's dumb". That's a shame because it's hand-down the best format. "Modern" development could learn a few things from it.

Info pages shine when it comes to material like this. It feels exactly like a book. If you're comfortable with the terminal, you get the advantage of Gnu's multipage online manuals locally on the terminal. It may feel hard to navigate - but it takes hardly an hour to learn the basic navigation, whether that be in Emacs, info or pinfo.

PS: Coincidentally, I was looking for a way to document my own program before release. I was looking at both formats, or perhaps choose something that can be converted into man, info and html. I'm open to any suggestion.

I hope it gives them the impetus to do a comic on getting and using documentation locally without the web and how to write more documentation. I guess in retrospect my love affair with that sort thing (info, and any other offline documentation) was due to having to use jigdo or even older tools to download a distro over a modem attached to a poor quality phone line, so having offline docs to refer to was a godsend.

If you've read manuals for, say, GNU Make, GNU Awk, GNU Libc or GCC online, you've read info documentation, even though you might not know what that is, and have never used the info program.

The GNU Awk man page is about 1600-something lines long; it doesn't compare to the manual.

The GNU Make man page renders to under 300 lines. Not the manual, obviously; you will learn next to nothing about GNU Make from that page.

If you install the GNU Make documentation, you can use "info make". I sometimes do that, but most of the time I go for the all-in-one-HTML-page online version. I mean, come on, you can just Ctrl-F search the whole page easily; it's a no brainer unless you need regex. Speaking of regex, the info pager searches are regex and you often need to backslash-escape characters when looking for code-related glyphs.

There is a way to read info pages all in one. Here is the trick, are you ready?

  info <whatever> | less

During the years, there have been many attempts to bridge the format gap, and convert texts from one representation to another. One of the most ambitious ones was in Tkman, a man viewer built on then Tcl/Tk system. Its really interesting part was the inclusion of rman, or RosettaMan, a converter of text to a somewhat abstract representation that could then be viewed via a GUI.

I personally look for well-crafted man pages as a sign of quality in software and try to provide them in everything I develop. I admit that I don't often find the time or motivation to write non-reference documentation (like tutorials).

In hindsight, it was just a better documentation format, it's a shame it didn't catch on.

Have you ever tried finding anything the the Bash manpage? It's the whole book! In one manpage!! For many tools, not just Bash, I often just use google to search the manpage, which really demonstrates a failure of our documentation tools.

And GNU's documentation is excellent. Isn't it a requirement for some of their projects (Emacs?) that a feature must be documented to be accepted?

With that said, Info's (the CLI command) UX seems to be a spin-off of Emacs, and just as obtuse to the new user. I'd accuse linux users of being hidebound for sticking to manpages, but Info is really challenging to navigate. I mean, xkcd.com/1343 has a point.

With the conflation with the Linux kernel, people sometimes forget.

If you want a „purer“ free UNIX, one of the BSDs might be a better fit.