This guidance on man pages for the GNU project is wild

I use info extensively for the GNU projects. As a user.<p>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.<p>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.<p>Try running “info gcc” or “info make” at some point and you’ll see something beautiful. You can browse linearly using space&#x2F;backspace, and Q to quit. You can do a text search across the whole manual, you can follow links, etc.<p>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.

In the replies, the author writes:<p>&gt; I literally did not know info pages existed for the first 15 years I used GNU tools, and I&#x27;ve still never used one<p>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.<p>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<p>1: <a href="https:&#x2F;&#x2F;www.gnu.org&#x2F;prep&#x2F;standards&#x2F;" rel="nofollow noreferrer">https:&#x2F;&#x2F;www.gnu.org&#x2F;prep&#x2F;standards&#x2F;</a>

I&#x27;ve written what could be the largest man page in the world, and possibly the only one that auto-numbers its sections down to three levels. I&#x27;ve written a bunch of smaller ones over the years, and when contributing patches to GNU programs, I did a tiny bit of Info documenting.<p>I can say with confidence that the language used for Info documentation is vastly superior to the nroff&#x2F;troff language. Man pages are not suitable for writing large manuals. It didn&#x27;t stop me, but what I&#x27;m doing is not really scalable.<p>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.<p>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.<p>I also wrote a minor tool which I use as a filter in CGIT which renders man pages. (It&#x27;s not used for that one; that&#x27;s too large and complex.) E.g. if you look at this small page, you can see it in action:<p><a href="https:&#x2F;&#x2F;www.kylheku.com&#x2F;cgit&#x2F;cppawk&#x2F;tree&#x2F;cppawk.1" rel="nofollow noreferrer">https:&#x2F;&#x2F;www.kylheku.com&#x2F;cgit&#x2F;cppawk&#x2F;tree&#x2F;cppawk.1</a><p>you see it as if you were reading it in man, rather than the source code, which you can see in the &quot;plain&quot; 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.<p>So the summary of man pages is: awful language + next to nonexistent tooling for publishing quality documents in multiple formats.<p>On the topic of troff, it&#x27;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&#x27;s likely what you will be using. So, in a way, GNU is committed to the troff language as much as to Info.<p>But GNU projects would be crazy to switch from Info to man; it&#x27;s an unthinkable regression.

Info is the best documentation system so far.<p>Use &#x27;s&#x27; for search (or &#x27;&#x2F;&#x27;).<p>Try &#x27;m&#x27; for menu,&#x27;i&#x27; for index, or &#x27;g&#x27; for go-to node. &#x27;t&#x27; for top.<p>Info manuals are like HTML websites except actually navigable. No menu on the left that contains 10,000 hits for the search term. It&#x27;s paginated, yet searchable across pages. Well written Info docs (anything core GNU) are indexed so that pressing &#x27;i&#x27; usually gets you there.<p>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&#x27;s spread across separate parts of the documentation. And that&#x27;s using a converted version, not something intended for Info. (Sphinx has Info as an output option.)<p>It feels like people&#x27;s reactions to Info is often, &quot;I don&#x27;t know this, therefore it&#x27;s dumb&quot;. That&#x27;s a shame because it&#x27;s hand-down the best format. &quot;Modern&quot; development could learn a few things from it.

Manpages outweigh info mindshare by a huge margin. And for most programs, a manpage is more than enough. But when your application is large enough to require a manual the size of a book, manpages simply aren&#x27;t enough. It&#x27;s too hard to arrange them properly or to search them up. A good example is git. Your system probably has the best and most comprehensive git material sitting in it as manpages. But even seasoned git users may not know about it.<p>Info pages shine when it comes to material like this. It feels exactly like a book. If you&#x27;re comfortable with the terminal, you get the advantage of Gnu&#x27;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.<p>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&#x27;m open to any suggestion.

If you read past the initial uninformed hot takes that thread actually gets progressively more interesting and informative. Good find.

Assuming the post isn&#x27;t trolling, it&#x27;s maybe worth mentioning that the GNU project doesn&#x27;t actually &quot;think everyone should use info pages.&quot; The document referenced is the standards for the GNU project. It&#x27;s hardly &quot;wild&quot; for a project to have a standard and to steer maintainers towards using it.

Such a strange take from someone I really respect who usually values digging into the why of things. I suppose we are all given to fits of pique on occasion but I don&#x27;t know how anyone could avoid using info for that long. Makes me sad a bit, others with far better credentials than I have explained the technical advantages in this thread already, but info pages are so much better, they taught me a lot of what got me my first jobs in the industry.<p>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.

Info pages are so much nicer than man pages: they have links between pages, organization and a much nicer viewer.

Many GNU programs have man pages that don&#x27;t have everything in them.<p>If you&#x27;ve read manuals for, say, GNU Make, GNU Awk, GNU Libc or GCC online, you&#x27;ve read info documentation, even though you might not know what that is, and have never used the <i>info</i> program.<p>The GNU Awk man page is about 1600-something lines long; it doesn&#x27;t compare to the manual.<p>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.<p>If you install the GNU Make documentation, you can use &quot;info make&quot;. 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&#x27;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.<p>There is a way to read info pages all in one. Here is the trick, are you ready?<p><pre><code> info &lt;whatever&gt; | less </code></pre> that&#x27;s it. Be gone, clumsy up&#x2F;down&#x2F;next&#x2F;prev navigation, and awkward searches.

In the whole spectrum of documentation, man pages were designed to cater for a very specific need: information-oriented reference data. Check <a href="https:&#x2F;&#x2F;documentation.divio.com&#x2F;" rel="nofollow noreferrer">https:&#x2F;&#x2F;documentation.divio.com&#x2F;</a> for a wonderful classification of documentation into four quadrants: reference, explanations, tutorials, and how-to guides. On the other hand, one can write info files for any of the use cases. That does not make info format inherently better or worse than man pages.<p>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&#x2F;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.<p>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&#x27;t often find the time or motivation to write non-reference documentation (like tutorials).

GNU project really likes to stick to its guns long after the battle is lost

I remember being confused by info pages when I first started using Linux some 20 years ago.<p>In hindsight, it was just a better documentation format, it&#x27;s a shame it didn&#x27;t catch on.

The manpage format is a ridiculous relic of a more limited era.<p>Have you ever tried finding anything the the Bash manpage? <i>It&#x27;s the whole book! In one manpage!!</i> For many tools, not just Bash, I often just use <i>google</i> to search the manpage, which really demonstrates a failure of our documentation tools.<p>And GNU&#x27;s documentation is <i>excellent</i>. Isn&#x27;t it a requirement for some of their projects (Emacs?) that a feature must be documented to be accepted?<p>With that said, Info&#x27;s (the CLI command) UX seems to be a spin-off of Emacs, and just as obtuse to the new user. I&#x27;d accuse linux users of being hidebound for sticking to manpages, but Info is really challenging to navigate. I mean, xkcd.com&#x2F;1343 has a point.

This is GNU in a nutshell. Wacky stuff driven by wacky individuals. They didn’t invent open source, just twisted what already existed into an “ism”. In this case, Stallmanism.

man pages are a UNIX thing. GNU is not UNIX.<p>With the conflation with the Linux kernel, people sometimes forget.<p>If you want a „purer“ free UNIX, one of the BSDs might be a better fit.