6 ms·

I was lucky to first be introduced to man pages by someone who often just called them "manuals" and (to my best recollection) explained them by telling me "Manu

• dfabulich 9y ago
  The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is fine, and then a list of options in alphabetical order which is almost always the least useful ordering. Categorize the parameters. Juxtapose confusingly similar options. And only then do we get any examples, if any. The examples should have come first, in the synopsis. There's nothing inherently wrong with man pages, but nobody has to follow this tradition. Put real examples in your synopsis and manually sort your options; you'll have a man page that's 20x better than most.
  • pletnes 9y ago
    I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway. man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addition to man pages.
    • deleted 9y ago
      [deleted]
    • jmfayard 9y ago
      A lot of us are "newbies" of "tar", "find", "[" and many others after years and years using *nix. According to the anti-usability mindset, this means that the users are wrong and ought to be changed, and not an hint that we should rethink how we write and consume documentation. Edit: the wording was angrier than it needed to be. A concrete example of a better documentation tool : https://kapeli.com/dash https://kapeli.com/dash
      • microcolonel 9y ago
        For what it's worth, find is truly awful, and tar is just a bit unconventional in terms of option parsing. These are stand-out failures of interface design, for which no documentation would be sufficient for all but the most regular of users.
      • rene_bg 9y ago
        Thanks for the link to Kapeli/Dash - looks like something that could really make everyday work easier!
      • mjw1007 9y ago
        Note that the commonly-used GNU implementations of tar and find both have info documentation which is much better than the manpages.
      • minusf 9y ago
        dash is web documentation kept offline with limited search added on top of it. it's basically a browser window...
        • dmitriid 9y ago
          Which already makes it orders of magnitudes better than man
  • microcolonel 9y ago
    > not even as a reference How are you supposed to write reference documentation without a section for describing the options which can be referred to by option name? > The examples should have come first, in the synopsis. Type with me: / E X A <return>. If anything, perhaps the first manual a man user should read is the manual for their default pager, usually LESS(1). There are good and bad manpages, but I don't see how the format is truly deficient. Some very complex commands have separate sections for the most and least common options (or groups of related options, if there are subcommands or similar).
  • unixhero 9y ago
    I agree. An an author of several command line tools I would never document it's usage in the way the classical man pages are structured. They are in times of dire need, frankly, unhelpful. I ALWAYS have to Google it, since the man page gave me nothing.
  • knolan 9y ago
    Even though I've fallen out of love with Matlab, its documentation is excellent. Brief description of the syntax for quick reference, a more detailed description, and finally detailed examples. Often there are references to the academic work behind the function and links to broader topics. Finally there's a bunch of related functions listed at the end which is great for discovering the vast array of Matlab's capabilities. For example: https://uk.mathworks.com/help/symbolic/svd.html https://uk.mathworks.com/help/symbolic/svd.html
  • jmfayard 9y ago
    Man is like javadocs: useless unless you already know what you are doing, and then usually a wordy paraphrase of the method signature :( Even as a reference manual, man is bad though. If I'm looking for option "-e" of the test command, why can't I do $ man test -e -e file True if file exists (regardless of type). That seems more efficient, more unix-friendly and not too much to ask. I get this is an historical tool that only cares about displaying the output of nroff. We would need a new tool with more empathy ($ woman? )
    • kleiba 9y ago
      De gustibus non est disputandum. I've found javadocs enormously helpful when I was learning Java 20 years ago. But then again, I also like man pages and use them a lot. If I'm looking for option "-e" of the test command, here's what I would do: $ man test and then "/-e". Searching within a document is a commonly required skill in so many situations that I don't even think twice when applying it in man pages. Of course, you could also just define a bash function for the functionality you're after like so: mano() { man "$1" | grep -A1 -- "$2" } and then do $ mano test -e or something along those lines.
      • jmfayard 9y ago
        That's full text search, not having directly the argument definition. If you search "-l" in "man ls", it will be only your 8th occurence.
        • kleiba 9y ago
          Sure, you're right, it's not the same thing. I just gave a simple example of something that's close, but I'm not even using a bash function like that myself. If I did, though, I guess the 8th occurrence wouldn't be so bad in my book, since the results can be scanned rather quickly. You could always make your function more clever, e.g.: function mano() { man "$1" | grep -A1 -- "$2\\b" } or function mano() { man "$1" | grep -A1 -- "$2 " } but most probably, you will still run into edge cases that won't work properly. For instance, only one of the two versions above still works with "test -e".
  • justin66 9y ago
    > The examples should have come first, in the synopsis. That is just a terrible idea. First, if what you're putting in the synopsis is not "a brief summary or general survey of something" then the section is misnamed or the content does not belong there. Examples don't belong there. Second, and more importantly, plenty of commands can do enough damage that people ought to read up on what they do before receiving an example. You're giving someone a false sense of confidence if you throw an example at them first thing. That's appropriate enough in some contexts, but not in official documentation for software tools. > The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. The problems you go on to list have nothing to do with the structure, and everything to do with the content contained within that structure. > No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. Since "documentation experts" write documentation this way, it's hard to imagine why you'd assert this.
    • xtiansimon 9y ago
      I share your reactions, with the exception that examples first or last seems irrelevant when using a man page—Sometimes it’s better first because you simply need a reminder how to use the command, and other times you need to read more of the description to catch the warnings before you use the command for the first or infrequent time. But if you follow the General best practice to read the whole of some documentation before you use a command, then this too seems irrelevant. That said, if you’re writing, reviewing, and editing documentation, the traditional structure is hierarchical and consistent—-which is good.
  • Annatar 9y ago
    and maybe Examples at the end) On a real UNIX like illumos and SmartOS, EXAMPLES are mandatory; I’ve no idea why people believe they may be optional, as they are one of the biggest reasons why someone would call up a manual page. It’s a manual.
• jap 9y ago
  I've integrated TLDR content into online man pages if you'd like to see both in one place. For example: https://www.mankier.com/1/grep https://www.mankier.com/1/grep
  • crispinb 9y ago
    Good idea. I just suggested something very similar before seeing your comment. Now all you need to do is write this up as a shell command ;)
• stinos 9y ago
  just called them "manuals" I'd be more specific: man vs tldr/bro is almost like an appliance's user manual vs service manual. The latter is super in depth but usually doesn't explain in an understandable way how to actually use the tool. While the former does that, but once you're stuck it offers no deeper explanation and you're lost.
• onetruepretzel 9y ago
  I must admit I'm not a fan of this. I feel like the work could go towards submitting patches to the man pages. The MAN page layout [0] allows for an EXAMPLES section which serves this purpose. Great effort in creating this tool but I think it's replicating functionality already provided by the man pages. I've submitted patches for MAN pages for GNU tools in the past and the creators are very receptive to updates. [0] - https://en.wikipedia.org/wiki/Man_page#Layout https://en.wikipedia.org/wiki/Man_page#Layout
  • dmitriid 9y ago
    Yup, and the examples section is usually last, with no possibility to jump directly to it
    • begriffs 9y ago
      You can jump to it by typing /EXAMPLES<enter> Or if that seems like a lot of keystrokes, /EX<enter> will probably jump to what you want most of the time too.
      • dmitriid 9y ago
        "probably" > man less /EX pattern not found /ex ends up somewhere in the middle of the text on a word that contains ex
    • crispinb 9y ago
      > and the examples section is usually last A far better answer to this would have been a project to (1) improve man page examples, and then (2) create a small alternative man page client that displays only the examples (or puts them up top). Having said that I do see the need for what tldr is doing, even though I would have preferred it added to existing tools. More often than not I only find man pages useful after I have needed to look up something. They're usually OK for wholistic understanding, but often too dense and assuming of far too much contextual knowledge to be useful in the heat of battle.
    • zaarn 9y ago
• agnivade 9y ago
  Maintainer here. > This TLDR tool definitely needs to exist, but in conjunction with man pages, not as a replacement. tldr is _exactly_ that. We do not and will not aim to replace man pages. We have a hard limit of 8 examples at max for every command. Therefore, our scope is very limited and we try to mention the 8 most important and practical examples a beginner needs to know for a command. If someone needs to go deeper, man pages are always there.