Editing 1343: Manuals
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
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?}} | ||
+ | |||
The chart shows the quality of tools regarding their manual: | The chart shows the quality of tools regarding their manual: | ||
− | *If you don't even need a manual to use | + | *If you don't even need a manual to use some tool, that tool tends to solve problems quickly. |
− | *If you do need a manual | + | *If you do need a manual the tool will probably not solve the problems quite as easy. |
− | * | + | *In contrast, however, 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 sudoers file | + | 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 | + | 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 mary vary depending on system, these were determined on openSUSE 12.3). |
==Transcript== | ==Transcript== | ||
− | + | {{incomplete transcript}} | |
− | |||
− | |||
− | |||
+ | :[There is a line with four bold dots on it] | ||
+ | :Above dot 1: A left-pointing arrow: "Solve problems" | ||
+ | :Below dot 1: "Tools that don't need a manual" | ||
+ | :Above dot 2 is a vertical dashed line. | ||
+ | :Below dot 2: "Tools that need a manual" | ||
+ | :Above dot 3: A right-pointing arrow: "Create problems" | ||
+ | :Below dot 3: "Tools that need a manual but don't have one" | ||
+ | :Below dot 4: "Tools whose manual starts with "How to read this manual" | ||
{{comic discussion}} | {{comic discussion}} | ||
− | |||
− |