I recently found myself wondering how big various man pages are. Some are so long, they seem impenetrable, while others have very little detail at all. What can their size tell us about the Linux or macOS system they are on?
How Do You Find the Biggest Man Pages?
The command line I used to find the biggest man pages looks like this:
du -a /usr/share/man | fgrep '.' | sort -rn | head -n 20
A fair bit is going on there, so let me explain.
Default man pages live in a hierarchy rooted at /usr/share/man. Inside that directory are sub-directories for each man section. Inside those are individual man page files like /usr/share/man/man1/grep.1 and /usr/share/man/man4/ip.4.
Man page files can live in several locations; the manpath command lists them. I’m after the most “stock” experience here, so I’m restricting my search to /usr/share/man, where the bulk of stock commands live.
The du command, for “disk usage,” shows you how much disk space files and directories are taking up. The -a option lists all files and directories in the hierarchy, with their block size alongside them. Block size isn’t quite the same as file size, but for this exercise, it’s close enough.
The pipe to fgrep removes the directories that du reports. Again, you can do this in better ways, but in the specific case here, it works fine.
The pipeline then uses sort with the -r and -n options to sort the output from du numerically with the largest numbers at the top. This works because du’s output includes the size as its first field.
Finally, head -n 20 gives the top 20 files. You could vary the number or replace the whole command with a pager like less to explore the full output.
What Are the Biggest Man Pages?
I checked two reasonably vanilla, Unix-like operating systems to see what their biggest man pages were:
On macOS, I saw the following:
So the biggest man pages are perltoc, perlapi, perlfunc, postconf, and perldiag. A lot of Perl!
On Ubuntu, the results are very different:
Notice how Ubuntu gzips its man pages. Text files often compress highly efficiently, so they take up a lot less space. But the biggest pages are less Perl-focused and include networking and sysadmin utilities.
Related
How to Zip and Unzip Files With Gzip on Linux
Save data storage space and shorten transmission times with gzip on Linux.
What the Biggest Man Pages Can Teach Us
You can learn a lot by reading them, but these pages also tell us some useful things about Linux, macOS, and which programs are the most heavyweight.
Perl Is Comprehensively Documented
On macOS, 4 of the 5 biggest man pages are Perl-related. I checked to see how many Perl man pages there were in total:
find /usr/share/man -name 'perl*'
214! Almost one-third of these are “delta” pages, like the one you get from man perl583delta:
These pages are the equivalent of release notes, and they are present for many minor versions of the language. This was one of the first things I learned through the process: some man pages don’t map directly to a command or installed program.
In contrast, there are just six perl* man pages on my Ubuntu machine. This isn’t really about the version of Perl that’s installed, either. On macOS, I see version 5.34.1 and on Ubuntu it’s 5.34.0.
zsh Is So Big, it Splits its Man Pages Into Several Smaller Ones
On macOS, I run zsh, and it turns out that this shell is well-represented when it comes to man pages. Inside the top 10 is a man page named “zshcompsys,” and the top 20 also includes zshcontrib, and zshmodules. Like Perl, zsh breaks its manual into separate pages; “only” 16 of them, though.
The zshcompsys page is a whopping 5,000 lines explaining how zsh’s tab-complete works. The completion system is incredibly powerful and configurable, so it’s understandable that this man page is so large.
This contrasts with other shells. The main bash man page is still big: #8 on the list and just under 5,000 pages. But there’s only one other bash-related manual page, bashbug, and it’s tiny, although it does document an interesting command that lets you file a bug report from the command line.
Other shells are well-represented—tcsh is at #9 in the list, and ksh at #20—but each of those shells restricts itself to just a single man page.
Meanwhile, on Linux, I use bash and this shell has the biggest man page overall. This checks out; I don’t have zsh installed and I would expect shell man pages to be among the biggest.
curl Is the Most Complex “Normal” Program
This was where my journey began, wondering if any other program was as complicated and well-documented as curl. The curl command has so many options, to deal with all the different features of HTTP, that its man page spans ~4,500 lines on Linux and ~6,500 on macOS. The difference is probably due to different versions of curl (8.7.1 on macOS, 7.81.0 on Ubuntu), but either way, it’s a mammoth manual.
When man pages reach this size, they start to become unwieldy. In curl’s case, I think there are two better alternatives. First, there’s tldr, a simpler alternative to man that focuses on example uses. Here’s what it makes of curl:
Those 32 lines are a lot more efficient than the 6,000 in the man page! The tldr page also mentions the second-best alternative: an online version of curl’s man page.
macOS Is More Focused on Section 1
man’s own man page describes section 1 as the “General Commands Manual.” On macOS, 18 of the largest 20 man pages are in section 1. In contrast, Ubuntu’s biggest man pages are much more diverse, distributed across sections 1, 3 (Library Functions), 5 (File Formats), and 8 (System Manager’s Manual).
The section 8 man page for openvpn is the second biggest on my system. It even warns the reader about its own length!
This probably reflects the primary users of each system. macOS is aimed at a broader consumer market, so even its terminal man pages are geared towards end-user commands. Linux appeals to programmers, sysadmins, and network operators, so its lower-level man pages are more comprehensive.
More Than Anything, I Learned to Be Curious Again
What started as a throwaway question I asked myself, developed into an exploration of Unix rabbit holes I’d never ventured into before. I knew the bare minimum about man pages, but my understanding of sections was limited, and I didn’t know about the manpath command at all. More importantly, I didn’t know much about the composition of man pages on my systems, and I certainly didn’t realize how much space they dedicated to Perl or git-config.
This exercise made me nostalgic for my earlier days with Linux, when everything was ripe for exploring. After years—even decades—of use, it’s easy to become complacent and stop asking questions about the underlying system. I’ve been reminded that peeking behind the curtain can be an effective way of learning, and I’ll try to feed that inquisitive nature just a little bit more in the future.
