5 ms·

People who complain about man pages tend not to understand man pages. Man pages aren't howto documentations. They're very specifically designed to document the

• coldtea 9y ago
  >People who complain about man pages tend not to understand man pages. That's their very issue with them. >Man pages aren't howto documentations. They're very specifically designed to document the different components of a command, call or configuration file. Then people who designed man pages didn't understand what the users want first and foremost: howto examples. Besides, whether they document "the different components of a command" and whether they have howto examples is orthogonal. They could do all the formal documentation they want and still include howto examples. That they don't (well, most don't, some man pages are decent enough to indeed include example sections) is their failure.
  • scaryclam 9y ago
    I don't think it's fair to say that the originators of man pages didn't understand what their users were looking for. In most cases, the authors are the users, and when they were first created, that was pretty much the only user base they had. Man pages are manual pages, not howto pages. If I'm looking at a man page, it's pretty much always because I want to look up one of the options, not how to use the command itself. Adding that sort of howto clutter would make it a whole lot harder to use the pages properly. Why not leave man pages alone and just focus on info pages again (http://www.troubleshooters.com/linux/info.htm http://www.troubleshooters.com/linux/info.htm)? That was always the go-to for more verbose descriptions and has much more of a howto vibe about it.
    • coldtea 9y ago
      >Man pages are manual pages, not howto pages. Isn't that a made-up distinction though? Who said manuals can't have representative examples for how to do certain tasks? Product manuals (including software product manuals) almost always do. They don't just enumerate features and flags.
      • iuguy 9y ago
        > Who said manuals can't have representative examples for how to do certain tasks? Dennis Ritchie defined what goes into the manual in the 3rd edition of UNIX, at the behest of Doug McEllroy. Ken Thompson also did some work on man pages, and I believe Lorinda Cherry was involved too. As I understand it (and I could be wrong though) the terseness of man pages was Ritchie's design, with input from Thompson.
        • coldtea 9y ago
          Which might have been good for late 70s -- and the main users being academics and the designers of the system itself, but might not be as good for late 2010s. Besides, we already have the Examples section, would it be too much to ask to have it better (or at least somewhat) utilized in all manpages? We could even have different sections, shown with flags, and keep regular output as it is. man --examples foocommand
          • iuguy 9y ago
            You clearly don't understand core Unix philosophy[1]. It's this that drives commands like man, that have been around since 3rd edition Unix. You're failing to understand who the main users of Unix were (Bell, a telecoms company. Academics didn't start using Unix in anger until the late 70s, by which point Unix had been established for about 3-7 years within AT&T/Bell depending on whether you count Berkeley and Illinois's initial use as academia, or it's more widespread adoption following the release of the BSD distribution and V7/V32). Before you start complaining about man pages, consider that in order to access them on your shiny new computer that it simulates a 1970s era virtual terminal, which itself emulates an advanced 1960s era teletype terminal to display it. The problem isn't man pages. They do their job generally well. The problem is that you want man pages to do something they aren't designed for, and will not change to. Use /usr/share/docs or info instead. That's what these things are there for. [1] - https://en.wikipedia.org/wiki/Unix_philosophy https://en.wikipedia.org/wiki/Unix_philosophy
  • iuguy 9y ago
    I pointed you directly at the correct sources of documentation: info pages (for most GNU software) and /usr/share/docs. These are the places where howtos belong, not man pages. The issue isn't with man pages themselves. The issue is with the expectations sites, tutorials and users themselves set for man pages.
• deleted 9y ago
  [deleted]
• Qwertious 9y ago
  "People who complain about man pages tend not to understand man pages." There could not be a more valid complaint. If the man pages aren't understandable, what program is supposed to explain them?
  • iuguy 9y ago
    There isn't really a single program. Man pages have been built through convention by people who've taken the time to write them, at various points following guidelines from Ritchie et al. It's usually down to the OS to explain the purpose and function of man pages in their own documentation. For some Operating Systems, man pages are exceptionally high quality (most notably the BSDs). For some, they're bilge, but such systems tend to have init managed through systemd. Having said that, many OSes support info(1), which provides more detailed software manuals for many pieces of software. Of course, there are actual physical locations for forms of documentation not in man format or structure. You can find out where such documentation lives on your system on most Unix-like OSes through man: $ man hier