Difference between revisions of "1343: Manuals"

Explain xkcd: It's 'cause you're dumb.
Jump to: navigation, search
(fix typo, clarify text)
(Explanation: Eliminated jargon. Article may still need work.)
Line 8: Line 8:
  
 
==Explanation==
 
==Explanation==
{{incomplete|The explanation regarding the title text is not easy to read for someone who do not use these "man tools". What does *nix for instance stand for? - Unix?}}
+
{{incomplete|The explanation regarding the title text is not easy to read for someone who do not use these "man tools".}}
  
 
The chart shows the quality of tools regarding their manual:
 
The chart shows the quality of tools regarding their manual:
Line 16: Line 16:
 
*Even worse are tools where the manuals start with a description of the manual itself (which implies that the manual is very hard to read).
 
*Even worse are tools where the manuals start with a description of the manual itself (which implies that the manual is very hard to read).
  
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|this famous comic]]. Man pages are collections of manuals for different tools, commands, files, and functions on *nix systems which can be viewed with the tool ''man''. You only need to type <code>man ''term-to-look-up''</code> in a terminal. There is even a manpage for ''man''. See for instance also the comic [[912: Manual Override]]
+
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|this famous comic]]. 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 <code>man ''term-to-look-up''</code> 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 {{w|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. This would be a very good example of a manual that starts with a section on "How to Read This Manual". Also, the [http://linux.die.net/man/5/sudoers sudoers man page] is very long, clocking in at 1504 lines. In contrast, the [http://linux.die.net/man/1/man manpages man page] only has 566 lines (Lines may vary depending on system, these were determined on openSUSE 12.3).
 
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 {{w|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. This would be a very good example of a manual that starts with a section on "How to Read This Manual". Also, the [http://linux.die.net/man/5/sudoers sudoers man page] is very long, clocking in at 1504 lines. In contrast, the [http://linux.die.net/man/1/man manpages man page] only has 566 lines (Lines may vary depending on system, these were determined on openSUSE 12.3).

Revision as of 17:25, 17 March 2014

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

Ambox notice.png This explanation may be incomplete or incorrect: The explanation regarding the title text is not easy to read for someone who do not use these "man tools".
If you can address this issue, please edit the page! Thanks.

The chart shows the quality of tools regarding their manual:

  • If you don't even need a manual to use some tool, that tool tends to help solve problems effectively.
  • If you do need a manual the tool will probably not solve the problems quite as easily.
  • Much less helpful are tools where you need a manual but do not have the manual - these tools tends to create more problems than they solve.
  • Even worse are tools where the manuals start with a description of the manual itself (which implies that the manual is very hard to read).

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 this famous comic. 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. This would be a very good example of a manual that starts with a section on "How to Read This Manual". Also, the sudoers man page is very long, clocking in at 1504 lines. In contrast, the manpages man page only has 566 lines (Lines may vary depending on system, these were determined on openSUSE 12.3).

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"


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