No problems with ideology when it’s right. Bundling documentation with the tool in a standard text format is the way to go. This can easily be reformatted for online wikis, manuals, etc.
Personally I never use either. If I want to know how to do something, my first instinct is to Google it or use ChatGPT. The information is a lot more easily compressed and searchable in a web browser than in CLI tools
If you know how to use info, it’s faster to find what you’re looking for than to use Google or ChatGPT. The interface is incredibly snappy and lets you do a full text search across the entire manual you are reading, quickly and without leaving the keyboard.
Not that there’s anything wrong with using Google or ChatGPT to find what you are looking for, but info is a fast way to get authoritative information, and the documentation is also mirrored on the web so it can be easily indexed by search engines and LLMs.
Assuming you always have convenient access to the internet. And that you version of the tool you are working with matches whatever result you find online.
And even then, often the best results you get from google come from the man or info page anyway.
My first search when googling documentation for a tool is often "man <toolname<"
I like to minimize the amount of time I spent with instant access to the web because too much instant access to the web is bad for my mental health. That's why I arranged things so that I don't need web access when I'm programming, and Info is a major part of my having been able to do that.
I just chose my most addictive sites and pointed them to 127.0.0.1 in my hosts file. When I open the browser and my Brian instinctively opens them, I get nothing.
For home projects, I have microsoft's docs on C++ and C# downloaded locally, but for work I need to be connected to the internet to do my job
I do that, too, in addition to keeping my cable modem off while I am programming (with the result that I have to wait about 8 minutes from any decision to use or access the web to when the web actually starts to be accessible to me).
Thanks for telling me that microsoft's docs on C++ and C# can be cached locally. I tried to create local copies of some docs on web programming, but found out that it cannot be done
with a reasonable amount of effort by people who are not already experts in web programming.
Yeah I'd say that chatgpt is wrong maybe 10 or 20% of the time. It generates old or straight up wrong information. You have to double check it against stackoverflow
Agreed. And I've been accused of it before (here, by dang).
But my point was that the gnu ideology was pushing contributors to use info pages (which many of us (myself included) tend to not use.
So perhaps the ideology should be reexamined from time to time. In this case, it should be: how do we make sure documentation is of highest quality and availability to our users (I'm more than happy to be challenged on that).
In that case, it might be worth considering making man pages a first class citizen again, along with html, as those are the natural destinations a user turns to when looking for help.
They remind me of the old saying: “separate the art from the artist.”
We need a new euphemism because that phrase doesn’t convey the level of ick one receives from it. Something like “with great power comes great fragility” or something.
I use info extensively for the GNU projects. As a user.
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.
This. One uses less all the time for displaying text files anyway, so the commands are in muscle memory. Using info is always similar to accidentally launching vi and not knowing how to get around or even out of it.
(I’ve learned vim in the meantime, but just avoided info for the last 10+ years)
And it's not like GNU is unique in having other documentation beyond man pages. Most FLOSS projects these days use man as a simple summary of command-line arguments, and have the rest of their documentation in HTML. The BSD folks are the only ones that have stuck to their guns of using man as the primary source of documentation. GNU man pages also helpfully tell you that more documentation is available in info format, which something many other projects don't do.
I’ve always struggled with the search command in info. Hitting / and the keyword then tapping next in man is easy. Info’s search always gets me tangled up, probably because I don’t use it enough to remember the keybinds.
The search in info is way better than the search in man. Check out info info for the docs.
Ctrl-S starts an I-search, instead of /. You then start typing what you want to search for. The results immediately appear; you don’t have to press enter. This will search across the docs for an entire project—with man, you may have to dig around with apropos first to find what you are looking for.
You can then hit Ctrl-S again to go to the next search occurrence, hit enter to stay where you are and exit the search, or Ctrl-G to exit the search and go back to where you started.
That's a big if. And I'm not going to learn to navigate an emacs system for a few utilities that I don't use much when everything that I do care about is on man.
Sure, content is king, as they say. If you spend all your time using tools/libraries/APIs with good man pages, then use man. If you spend your time using GCC, Make, Bison, etc., then you’d be better off learning info.
You’d equally not learn how to navigate Javadoc if you don’t write Java code. Seems pretty obvious to me.
I get that info is a little easier if you are used to Emacs keybindings. But if you use info, you’d mostly just use space / backspace, ctrl-s for search, m for menu, and u for up. It’s not a lot of keybindings that you’re probably going to end up using. Yeah, info has M-x, but who ever uses it? Everyone who used man for the first time had to learn those keybindings too.
I spent my early developer life using Perl. Which had perldoc pages that were mirrored to man pages.
The few times I ventured into info pages, I found the information scattered and hard to skim because it was divided up inconveniently.
While it is true that I must have learned the keybindings for man at one point, they are the same as the keybindings for vi and less. Both of which I frequently used for unrelated purposes, and so were firmly in my muscle memory.
This usually means you haven’t installed the info pages: info falls back to manpages if it can’t find an info-native page. Typically, on Debian or similar, you have to install foo-doc to get the info pages if `foo` doesn’t install them. E.g. I’m fairly sure the zsh package lacks the very good zsh info pages, which are included in zsh-doc.
Way back when, the emacs-ish interface that info uses by default was very jarring, especially since I had been using vim forever.
`pinfo` was a browser that supported browsing like elinks, and the keybindings were similar enough that I could effectively navigate it when needed.
However, IMHO, as nice and organized as the info pages were, every modern console I found myself using, when in the terminal, when I needed to use man or info, I really just wanted a a summary of all the command line options, that I could grep on, in one big list. info pages tended to offer logical subsections, that required more interaction + more careful reading to get to the piece of info you were after, which ended up using more time to plow through to a solution.
IMO, if you’re just interested in grepping through options, info is better at that, compared to man. I feel like I’m fighting against man when I look at the man page for SoX or rsync. I find some --option listed in the option list, but I want to see more details about how it works—but when I grep for --option, I have to scroll past 20 or 30 references to --option like, “--something is similar to --option except X, Y, Z”. It’s a complete slog just looking up an option.
In info, I can find this information a lot faster.
I love info pages. I spent many hours trying to convert documentation I use into info pages or something like info (but failed, as info has more metadata than those sources).
Sure enough I’m using Emacs but navigating through any documentation in info form is a very positive experience, especially in comparison to a documentation in HTML form that has many issues (especially since interactivity for search etc. is inconsistent and likes to break)
What you say may be true, but never the less, when I first encountered it and tried it, I could not stand it. Just as a user not as an author. I've never looked at it since. I do like good old simple man pages as long as they aren't the stubs that just say "see the info".
Maybe it was just the keybindings, maybe it was something about the screen layout and navigation hints (lack of maybe). I can't say precisely what was so wrong, and have no interest in even trying nor need to.
If it was so great, no one would need to try to convince anyone of anything. I'd have just used it in prefference because it was better at getting the info I wanted to me.
Hierarchies aren't All That. The case for hierarchies only makes sense when the
ontology is familiar to the user[1]. Without knowing the info hierarchy it's impossible to navigate. Why, for example, are the gnupg info pages under 'GNU Utilities', wget under 'Network applications', and things like rm and mkdir under 'Individual utilities' (a long with dozens of other things)?
The hierarchy within the info page is where it’s useful. You don’t look for gnupg by going into GNU Utilities, you go to gnupg by typing "info gnupg".
Within the gnupg manual you can look at a section like “key management commands” or something like that. There are a lot of different commands in gnupg, it’s nice to have a separate page for each, and be able to browse.
By comparison, the OpenSSL docs are man pages, and it kinda sucks to browse the OpenSSL docs. (I’m gonna say, categorically, that both OpenSSL and GnuPG have bad UX. It kinda sucks to figure out what you’re doing in either case, but at least the GnuPG manual is easier to read.)
I'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'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.
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:
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.
Writing man pages by hand is indeed something that makes you lose the will to live. For anything beyond the trivial case I just write Markdown and convert it to a man page using pandoc.
It basically contains a really hacky, spaghetti-coded nroff interpreter. Very nasty C code.
In some of the patches, I actually implement missing features, like if/else conditions and loops. I got it to handle some of the complex macros in the TXR man page.
I also put in a way where the man page can detect that it's being processed by that man2html program to do some things differently, that work better for HTML. If the M2 variable is present, then the nroff processor is confirmed to the man2html.
There is a three-way if for targeting macros that annotate key strokes (used in the part of the manual that documents the REPL). In man2html, we generate inline HTML <kbd>...</kbd> tags. In nroff (man paging) we put square brackets, like [Ctrl-C], and for PDF output via groff, I used a complex copy pasta from the Groff manual to render boxes.
> 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
Is it possible this is less of a reflection of the author's abilities and more of a reflection of your lack of imagination? Not everyone who reaches a destination follows the same path. Stack Overflow was launched just over 15 years ago, for what it's worth.
I think it's not that you don't stumble, it's just that you avoid them concsiously or subconsciously.
For me it's almost 20 years now but the reflex is still "check the man quickly, then go to full html docs if necessary". It developed very early and then I never applied enough force to break it.
When thinking of my early Linux usage experience I guess the primary reasons why the reflex developed were the following:
1) In the beginning you barely understand what's happening and turn to docs very frequently, often feeling desperation by that point. Figuring out a complex interface in this state of mind feels extremely frustrating, because you're already in process of figuring out something else. Man/less interface is very limited but it's also comforting in its simplicity.
2) When you finally subside to the "info xxx should give you access to the complete manual" instruction it shows you the same man page but in a frustrating interface which feels like a cruel joke (you're desperate to solve something, remember). I didn't have doc packages installed and I had no way of knowing that at the time. I still think it's a horrible usability solution and if "info" showed the install instructions instead the story could have been different.
Issue #1 can be sidestepped by using the HTML docs, which are still info pages.
Issue #2, I think, is a packaging issue related to licensing and the peculiarities of Debian packaging rules. Normally, any time you install a package, you get the man pages and info pages.
Everything can be sidestepped, it's not the point. The point is for some users (a majority I suspect) info pages have the entry barrier too high. Not very high per se, but too high compared to what you normally expect from documentation which is no entry barrier at all. That happens due to an unfortunate combination of circumstances most of which have nothing to do with info pages format itself which is quite good.
It's much easier to search man pages for information.
/foo<enter>
For quick search for an option or argument, man is better than info. For in depth documentation, info is better. Usually, a man page is a brief summary of program documentation.
This works for me and it searches the whole info manual. But, I do agree that there’s a trade off here between in-depth documentation and easy to scan docs.
You can also sometimes do something like “info zsh …” to jump directly to a sub-page and, at least in zsh, tab completion works for these sub pages.
The manpage format is a ridiculous relic of a more limited era.
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.
> The manpage format is a ridiculous relic of a more limited era.
If you read the thread, you will see the claim: ”Info pages are older than man pages (the format dates back to ITS on the PDP-10).” - by a guy, going by the handle @amszmidt - so they’re both, from the same ‘limited era’, near enough.
> Have you ever tried finding anything the the [sic] Bash manpage?
Yes, all the time. The beauty of Unix style man pages, is they rely on the user(s) native $PAGER - so the search capabilities, are dependent upon what one chooses, for such - rather than the incredibly clunky, GNU thingy, that comes bundled with the info system, unfortunately…
Unix man pages, are also excellent - as they haven’t been deliberately crippled, in order to try and forcefeed us the info gruel… - in much the same way, that GNU Guile, was chosen as the “official” extension language, over TCL, for political reasons.
You can use a web browser for the info pages, and you get some reasonable HTML when you export this.
I don’t see justification for saying that info is klunky. “I haven’t learned to use it” is valid, “I don’t want to learn another thing” is valid, but all the functionality that you want is right there at your fingertips. It’s not klunky just because it’s not exactly the same as your pager. And if you just want to use your pager, you can pipe info to your pager, you just lose the hyperlinks. Or you can keep the hyperlinks and use the web browser.
Unix man pages are excellent but most parts of Unix are small enough that the docs fit in man pages. Say what you will about the “Unix philosophy”, but the Unix reality is that we use a lot of programs where the docs are too large to fit reasonably into a man page. GCC, Bash, Make, Bison, Flex, etc. Some of these tools are heading the way of the dodo.
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't enough. It'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.
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.
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.
Many GNU programs have man pages that don't have everything in them.
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
that's it. Be gone, clumsy up/down/next/prev navigation, and awkward searches.
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'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.
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.
Assuming the post isn't trolling, it's maybe worth mentioning that the GNU project doesn't actually "think everyone should use info pages." The document referenced is the standards for the GNU project. It's hardly "wild" for a project to have a standard and to steer maintainers towards using it.
In the whole spectrum of documentation, man pages were designed to cater for a very specific need: information-oriented reference data. Check https://documentation.divio.com/ 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.
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).
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.
75 comments
[ 4.2 ms ] story [ 132 ms ] threadNot that there’s anything wrong with using Google or ChatGPT to find what you are looking for, but info is a fast way to get authoritative information, and the documentation is also mirrored on the web so it can be easily indexed by search engines and LLMs.
And even then, often the best results you get from google come from the man or info page anyway.
My first search when googling documentation for a tool is often "man <toolname<"
For home projects, I have microsoft's docs on C++ and C# downloaded locally, but for work I need to be connected to the internet to do my job
Thanks for telling me that microsoft's docs on C++ and C# can be cached locally. I tried to create local copies of some docs on web programming, but found out that it cannot be done with a reasonable amount of effort by people who are not already experts in web programming.
I think I would prefer we just ship folders of markdown or HTML that open with your editor/viewer of choice though.
But my point was that the gnu ideology was pushing contributors to use info pages (which many of us (myself included) tend to not use.
So perhaps the ideology should be reexamined from time to time. In this case, it should be: how do we make sure documentation is of highest quality and availability to our users (I'm more than happy to be challenged on that).
In that case, it might be worth considering making man pages a first class citizen again, along with html, as those are the natural destinations a user turns to when looking for help.
We need a new euphemism because that phrase doesn’t convey the level of ick one receives from it. Something like “with great power comes great fragility” or something.
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’ve learned vim in the meantime, but just avoided info for the last 10+ years)
I guess I'm one of today's lucky 10,000. [1]
I'm tempted to make my tools do something similar. On Windows too.
[1]: https://xkcd.com/1053/
Ctrl-S starts an I-search, instead of /. You then start typing what you want to search for. The results immediately appear; you don’t have to press enter. This will search across the docs for an entire project—with man, you may have to dig around with apropos first to find what you are looking for.
You can then hit Ctrl-S again to go to the next search occurrence, hit enter to stay where you are and exit the search, or Ctrl-G to exit the search and go back to where you started.
That's a big if. And I'm not going to learn to navigate an emacs system for a few utilities that I don't use much when everything that I do care about is on man.
You’d equally not learn how to navigate Javadoc if you don’t write Java code. Seems pretty obvious to me.
I get that info is a little easier if you are used to Emacs keybindings. But if you use info, you’d mostly just use space / backspace, ctrl-s for search, m for menu, and u for up. It’s not a lot of keybindings that you’re probably going to end up using. Yeah, info has M-x, but who ever uses it? Everyone who used man for the first time had to learn those keybindings too.
The few times I ventured into info pages, I found the information scattered and hard to skim because it was divided up inconveniently.
While it is true that I must have learned the keybindings for man at one point, they are the same as the keybindings for vi and less. Both of which I frequently used for unrelated purposes, and so were firmly in my muscle memory.
My experience was, with 1 or 2 exceptions, that the info was the same as the manpage. And navigating info pages is "challenging".
`pinfo` was a browser that supported browsing like elinks, and the keybindings were similar enough that I could effectively navigate it when needed.
However, IMHO, as nice and organized as the info pages were, every modern console I found myself using, when in the terminal, when I needed to use man or info, I really just wanted a a summary of all the command line options, that I could grep on, in one big list. info pages tended to offer logical subsections, that required more interaction + more careful reading to get to the piece of info you were after, which ended up using more time to plow through to a solution.
In info, I can find this information a lot faster.
I love info pages. I spent many hours trying to convert documentation I use into info pages or something like info (but failed, as info has more metadata than those sources).
Sure enough I’m using Emacs but navigating through any documentation in info form is a very positive experience, especially in comparison to a documentation in HTML form that has many issues (especially since interactivity for search etc. is inconsistent and likes to break)
GNU might not be unix, but alas worse is still better.
Maybe it was just the keybindings, maybe it was something about the screen layout and navigation hints (lack of maybe). I can't say precisely what was so wrong, and have no interest in even trying nor need to.
If it was so great, no one would need to try to convince anyone of anything. I'd have just used it in prefference because it was better at getting the info I wanted to me.
Hierarchies aren't All That. The case for hierarchies only makes sense when the ontology is familiar to the user[1]. Without knowing the info hierarchy it's impossible to navigate. Why, for example, are the gnupg info pages under 'GNU Utilities', wget under 'Network applications', and things like rm and mkdir under 'Individual utilities' (a long with dozens of other things)?
1. https://web.archive.org/web/20070119210402/http://www.shirky...
Within the gnupg manual you can look at a section like “key management commands” or something like that. There are a lot of different commands in gnupg, it’s nice to have a separate page for each, and be able to browse.
By comparison, the OpenSSL docs are man pages, and it kinda sucks to browse the OpenSSL docs. (I’m gonna say, categorically, that both OpenSSL and GnuPG have bad UX. It kinda sucks to figure out what you’re doing in either case, but at least the GnuPG manual is easier to read.)
In hindsight, it was just a better documentation format, it's a shame it didn't catch on.
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.
https://man.freebsd.org/cgi/man.cgi?query=mdoc
https://man.freebsd.org/cgi/man.cgi?query=groff_mdoc
I had to go see for myself and it is indeed around six times larger than the bash man page. I endorse this nomination.
I applied quite a lot of changes to it.
It basically contains a really hacky, spaghetti-coded nroff interpreter. Very nasty C code.
In some of the patches, I actually implement missing features, like if/else conditions and loops. I got it to handle some of the complex macros in the TXR man page.
I also put in a way where the man page can detect that it's being processed by that man2html program to do some things differently, that work better for HTML. If the M2 variable is present, then the nroff processor is confirmed to the man2html.
There is a three-way if for targeting macros that annotate key strokes (used in the part of the manual that documents the REPL). In man2html, we generate inline HTML <kbd>...</kbd> tags. In nroff (man paging) we put square brackets, like [Ctrl-C], and for PDF output via groff, I used a complex copy pasta from the Groff manual to render boxes.
> 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/
Especially if you’re a developer.
EDIT: fix typo
For me it's almost 20 years now but the reflex is still "check the man quickly, then go to full html docs if necessary". It developed very early and then I never applied enough force to break it.
When thinking of my early Linux usage experience I guess the primary reasons why the reflex developed were the following:
1) In the beginning you barely understand what's happening and turn to docs very frequently, often feeling desperation by that point. Figuring out a complex interface in this state of mind feels extremely frustrating, because you're already in process of figuring out something else. Man/less interface is very limited but it's also comforting in its simplicity.
2) When you finally subside to the "info xxx should give you access to the complete manual" instruction it shows you the same man page but in a frustrating interface which feels like a cruel joke (you're desperate to solve something, remember). I didn't have doc packages installed and I had no way of knowing that at the time. I still think it's a horrible usability solution and if "info" showed the install instructions instead the story could have been different.
Issue #2, I think, is a packaging issue related to licensing and the peculiarities of Debian packaging rules. Normally, any time you install a package, you get the man pages and info pages.
You can also sometimes do something like “info zsh …” to jump directly to a sub-page and, at least in zsh, tab completion works for these sub pages.
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.
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.
If you read the thread, you will see the claim: ”Info pages are older than man pages (the format dates back to ITS on the PDP-10).” - by a guy, going by the handle @amszmidt - so they’re both, from the same ‘limited era’, near enough.
> Have you ever tried finding anything the the [sic] Bash manpage?
Yes, all the time. The beauty of Unix style man pages, is they rely on the user(s) native $PAGER - so the search capabilities, are dependent upon what one chooses, for such - rather than the incredibly clunky, GNU thingy, that comes bundled with the info system, unfortunately…
Unix man pages, are also excellent - as they haven’t been deliberately crippled, in order to try and forcefeed us the info gruel… - in much the same way, that GNU Guile, was chosen as the “official” extension language, over TCL, for political reasons.
I don’t see justification for saying that info is klunky. “I haven’t learned to use it” is valid, “I don’t want to learn another thing” is valid, but all the functionality that you want is right there at your fingertips. It’s not klunky just because it’s not exactly the same as your pager. And if you just want to use your pager, you can pipe info to your pager, you just lose the hyperlinks. Or you can keep the hyperlinks and use the web browser.
Unix man pages are excellent but most parts of Unix are small enough that the docs fit in man pages. Say what you will about the “Unix philosophy”, but the Unix reality is that we use a lot of programs where the docs are too large to fit reasonably into a man page. GCC, Bash, Make, Bison, Flex, etc. Some of these tools are heading the way of the dodo.
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.
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.
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?
that's it. Be gone, clumsy up/down/next/prev navigation, and awkward searches.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.
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).