1343: Manuals

Explain xkcd: It's 'cause you're dumb.
Jump to: navigation, search
Manuals
The most ridiculous offender of all is the sudoers man page, which for 15 years has started with a 'quick guide' to EBNF, a system for defining the grammar of a language. 'Don't despair', it says, 'the definitions below are annotated.'
Title text: The most ridiculous offender of all is the sudoers man page, which for 15 years has started with a 'quick guide' to EBNF, a system for defining the grammar of a language. 'Don't despair', it says, 'the definitions below are annotated.'

Explanation[edit]

The chart shows the quality of tools regarding their manual:

  • If you don't even need a manual to use a certain tool, that tool tends to help solve problems effectively.
  • If you do need a manual, the tool will probably solve the problems but you have to understand that manual before you can use this tool effectively.
  • Much less helpful are the tools where you need a manual but it doesn't exist — these tools tend to create more problems than they solve.
  • But the worst tools are where the manuals start with a description of the manual itself — which implies both that the tool is very complex and the manual is very hard to understand.

The title text refers to sudoers, a config file for the unix command sudo. sudo allows users to run a program with elevated permissions, as referenced in 149: Sandwich. Man pages are collections of manuals for different tools, commands, files, and functions on Unix-like systems which can be viewed with the tool man. You can type man man in a terminal to get the manpage for the manual program. See for instance also the comic 912: Manual Override.

The sudoers file specifies which users have sudo access, and which commands they are allowed to run as other users (typically root). The syntax of the file is very complex, and the manpage uses the Extended Backus–Naur Form (or EBNF) to describe the syntax. The sudoers man page starts off with an explanation of EBNF's grammar, which they reference throughout the rest of the man page in describing the syntax of the sudoers file. The sudoers man page is very long, clocking in at 1504 lines. In contrast, the manpages man page only has 566 lines. The number of lines may differ between some distributions and versions.

The title text also notes that the manual's assurance, "don't despair" because "the definitions below are annotated", fails to be reassuring, and instead merely emphasizes the length and complexity of the document to read.

Transcript[edit]

[A horizontal line has four points labeled on it, with the second point from the left marked with a dashed vertical line dividing the horizontal line into two parts.]
[An arrow labeled "Solve problems" points left from the vertical line.]
[An arrow labeled "Create problems" points right from the vertical line.]
[The points are labeled, from left to right, "Tools that don't need a manual", "Tools that need a manual", "Tools that need a manual but don't have one", and "Tools whose manual starts with 'how to read this manual'".]


comment.png add a comment! ⋅ comment.png add a topic (use sparingly)! ⋅ Icons-mini-action refresh blue.gif refresh comments!

Discussion

Your line counts may vary for the man pages, depending