1343: 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.'

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 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.

[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'".]

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)

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)

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)

Search

Navigation

Tools

It seems you are using noscript, which is stopping our project wonderful ads from working. Explain xkcd uses ads to pay for bandwidth, and we manually approve all our advertisers, and our ads are restricted to unobtrusive images and slow animated GIFs. If you found this site helpful, please consider whitelisting us.