1343: Manuals

|< < Prev Comic #1343 (March 17, 2014) Next > >|

Manuals

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

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 until 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 that 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 only need to type man term-to-look-up in a terminal. There is even a manpage for man. 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 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

[A line graph evidently relating tools, their documentation, and their ability to solve problems. There are four points on the line, one to the left and two to the right of a midpoint.]

[label to left of midpoint] Solve problems

[point to left of midpoint] Tools that don't need a manual

[midpoint] Tools that need a manual

[label to right of midpoint] Create problems

[point to right of midpoint] Tools that need a manual but don't have one

[point farther to right of midpoint] Tools whose manual starts with "How to read this manual"

 add a comment! ⋅  add a topic (use sparingly)! ⋅  refresh comments!

Discussion

Your line counts may vary for the man pages, depending on what distribution you are running and what version of man you're using (and god forbid, what version of wc). ‎108.162.221.51 (talk) (please sign your comments with ~~~~)

it may even vary based on the number of columns in your terminal, as man pages are formatted from their roff sources when you type 'man foo'... 108.162.229.72 07:06, 28 March 2014 (UTC)

Mine comes in at 1806 lines. So even more unwieldy. (Ubuntu 13.10) 108.162.216.74 14:36, 17 March 2014 (UTC)

1,743 here... but that's still only medium length; g++ weighs in at 14,148 (Fedora 20). 173.245.52.29 19:09, 17 March 2014 (UTC)

g++ might be 14,148, but it is also a compiler. In fact it's a collection of compilers, optimizers, linkers, preprocessors, optimizers, lexers, parsers, partridges, and pear trees. sudoers is a config file. 108.162.221.5 00:30, 19 March 2014 (UTC)

I seem to remember some info page starting with “how to read this manual”… can’t find it though. --108.162.254.162 10:00, 17 March 2014 (UTC)

I believe the implication is that the "how to read this manual" section is a manual for the manual. This could be characterized as an instance of recursion. 173.245.54.52 16:07, 17 March 2014 (UTC)

Cool. I had been wondering what that grammar-description syntax was called and how it worked. Now I know where to read about it! I do wonder about how true the cartoon is, though. Notepad does not require a manual or tutorial, but vi and Emacs do. Jim E (talk) 16:10, 17 March 2014 (UTC)

Did you seriously just compare a Windows and a Unix tool? In my opinion though, notepad/nano are more useful. 108.162.221.43 17:49, 17 March 2014 (UTC)

Trolling? Spongebog (talk) 19:24, 17 March 2014 (UTC)

If not trolling should at least read man nano before saying "notepad/nano". 108.162.221.5 19:21, 18 March 2014 (UTC)

Is this spelling correct: "that tool tends", but "these tools tend"? I'm not native English so maybe someone can help. --Dgbrt (talk) 20:47, 17 March 2014 (UTC)

Yes, those are both correct English. "That tool" is singular while "these tools" is plural, thus the verbs are (singular) "tends" and (plural) "tend". There is a mistake in the fourth bullet where the person who wrote the explanation said "most worse" (should have said "worst": "But the worst tools..."). 108.162.221.84 (talk) (please sign your comments with ~~~~)

Many thanks for your reply. Your last statement is covered now. Many thanks for your help! But please don't forget to sign your post. Maybe you should create an account here, it's much easier to talk. --Dgbrt (talk) 22:59, 17 March 2014 (UTC)

Could this comic itself be considered a manual for how to determine whether a tool causes or creates problems? 173.245.54.89 21:02, 17 March 2014 (UTC)

I think this comic is a tool, rather than a manual, a tool to determine whether a tool fixes or creates problems. This tool needs/has a manual (this wiki page). At least this wiki page doesn't include a section called "How to read this xkcd explanation". 108.162.221.5 19:26, 18 March 2014 (UTC)

Would not the "Help" link on the left be classed as a manual for this page? DD (talk) 09:27, 19 March 2014 (UTC)

Yeah, but do you need the help for reading this wiki? --108.162.254.196 12:09, 19 March 2014 (UTC)

It's 2021 and the sudoers man page still has a mini-manual for a grammar-generation syntax. Nitpicking (talk) 23:35, 29 November 2021 (UTC)