What might be somewhat more surprising though considering its research origins is that Unix almost since the very beginning had a comprehensive set of online reference documentation for all its commands, system calls, file formats, etc. These are the the manual- or man-pages. On Unix systems used interactively, the man-pages have historically always been installed, space permitting.
[…]The way the manual pages have evolved and how they are used has changed over the decades. This set of posts is intended to give people unfamiliar with them an overview, as well as offer a review to seasoned users.
↫ Alex Bochannek
Right in this first article in the series there’s an interesting observation I never stopped and thought about: because the original creators of UNIX were writing the content of man pages with the very tools they were creating for UNIX, it led to a virtuous cycle. “Unix tools were used to document Unix, improving the documentation tools themselves as well.” I tend to use the internet now to learn how specific tools and commands work, but having such detailed man pages built right into the operating system was a huge deal pre-internet.
Its pretty common in small containers to not have Man pages installed, which I understand space concerns and everything, but always annoying. Its like all the arguments from the 80’s around space are back. Many times even vi ( not vim) isn’t included making any on container work a pain.
Highly recommend checking out the “History of UNIX Manpages”, a comprehensive history from the mandoc/bsd.lv folks.
https://manpages.bsd.lv/history.html
I was pretty annoyed when the Steam Deck didn’t come with any man pages installed at all (obviously not needed in Gaming Mode, but definitely needed in Desktop Mode when using the terminal). I ended up writing a script to install a bunch of missing things – including man pages – although I have to re-run the script after any SteamOS updates. In case you’re curious, other things missing were fwupd (needed this to update the firmware on an SSD I’d installed internally as an upgrade), vi (yes, it’s missing!), old school network tools (ifconfig/nslookup etc) and en-GB support (internationalisation had been stripped out) to name but a few.
To be honest, I didn’t even know the Steam Deck doesn’t come with man pages. I never needed to use them. On mine, I only rarely use desktop mode, in very specific situations. I’d probably be more likely to pull out my phone and look up the man page in a web browser on that before even opening a browser on the Steam Deck. Anything I do on my Steam Deck, if I’m not playing games, I’m doing with the specific purpose of getting a game to work. But, mine is docked to a TV with an Xbox controller, I try to avoid having to use a keyboard or mouse if at all possible.
I do recommend tldr as a quick tool to learn how to use a command with common examples. I don’t understand why such tools are not more commons. It is so much easier to get started than man pages or AI generated webpages.
I have been using Chimera Linux a bit which comes with the BSD core utils and I have been reading the man pages. My favourite is the HISTORY section as they explain when the command and command-line options were added going all the way back to the beginning (all the way back to AT&T and the early BSDs).
For example, here is the BSD man entry for the man command itself (the one in Chimera Linux at least):
HISTORY
A man command first appeared in Version 2 AT&T UNIX.
The -w option first appeared in Version 7 AT&T UNIX; -f and -k in 4BSD;
-M in 4.3BSD; -a in 4.3BSD-Tahoe; -c and -m in 4.3BSD-Reno; -h in
4.3BSD-Net/2; -C in NetBSD 1.0; -s and -S in OpenBSD 2.3; and -I, -K, -l,
-O, and -W in OpenBSD 5.7. The -T option first appeared in AT&T
System III UNIX and was also added in OpenBSD 5.7.
In contrast, the GNU man commands (if they even have a HISTORY) only detail their own history. Here is the GNU man entry for man:
HISTORY
1990, 1991 – Originally written by John W. Eaton (jwe@che.utexas.edu).
Dec 23 1992: Rik Faith (faith@cs.unc.edu) applied bug fixes supplied by Willem Kasdorp (wkasdo@nikhefk.nikef.nl).
30th April 1994 – 23rd February 2000: Wilf. (G.Wilford@ee.surrey.ac.uk) has been developing and maintaining this package with the help of a few dedicated people.
30th October 1996 – 30th March 2001: Fabrizio Polacco maintained and enhanced this package for the Debian project, with the help of all the community.
31st March 2001 – present day: Colin Watson is now developing and maintaining man-db.
I hate GNU with a passion for having useless stubs of man pages that just tell you to go look at the “info” page.
“Oh good, I didn’t want a quick rundown of the options, I wanted to go read through a full book about this program I barely ever use…”
Notwithstanding GNU’s annoying “principles”, which software package still does this? I went through the list trying to find one, and I couldn’t:
https://www.gnu.org/software/
My guess is you’re referring to not pointing people to “info” but using a website. I mean, it’s still the whole “spirit of the thing” though. Man page tells you “some things” except the important stuff, for that, you have use a browser and the Internet.
I was simply referring to the fact that there aren’t (m)any GNU software packages without decent man pages these days.
And, in general, their quality is pretty decent. There are still a few packages (aspell, m4, info itself) whose man pages are quite short and refer the reader to info. But these are generally the legacy ones. Most widely used packages (coreutils, bash, gawk, gcc, etc.) come with both good quality man pages and good quality info pages. And some others (mc, gimp) don’t even have an info page at all.
Personally, I think man pages are still the best option for getting help when programming or using the CLI. Which isn’t at all bad bad for a 50 year old design. But I agree that there are now many use cases for which they’re inadequate. You can’t get help for gimp without using the web.
They should be for different things thought. Man for a quick rundown of all options, and info for the full documentation.
Last year, I began an effort to create a modern TUI viewer for man pages:
https://github.com/plp13/qman
Working on it was great fun. It brought to light all sorts of little-known minutia, from character sequences emitted by groff in order to retain compatibility with 1970s typewriters, to terminal escape sequences that enable dragging the mouse and copying text into the clipboard.
It also made me think of how nice it would have been if man pages were superseded by a more modern format. One that is human-readable, has decent semantics, and doesn’t depend on typesetting software from 1970. Many formats exist that can be used as a starting point (e.g. Markdown). The real challenge, however, would be translating all the existing man pages to the new format. Groff is ancient, and thus unaware of modern(er) concepts such as hyperlinks and differentiating text from code. Inferring these won’t be easy. Perhaps a combination of heuristic algorithms or generative AI, together with a lot of manual proofreading, could do the trick.
Amen. Sing it. It is both everything that is good and bad about man pages…and the downside of being around for basically 50 years.