Hacker News Reader

Comment by dfabulich | Hacker News Reader

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.

View on HN

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.

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

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.

Thanks for the link to Kapeli/Dash - looks like something that could really make everyday work easier!

Note that the commonly-used GNU implementations of tar and find both have info documentation which is much better than the manpages.

dash is web documentation kept offline with limited search added on top of it. it's basically a browser window...

Which already makes it orders of magnitudes better than man

But why? You already can search through man pages with / key in your $PAGER (more/less/most/vimpager), and across pages with `man -k`/`man -K`, and I wouldn't really call proportional fonts as "orders of magnitude" better.

Why should good documentation not be bundled with the product?

Sure. Cmake has a brief man page and a big bulky HTML manual.

Good projects should have tutorials and complete references online in addition to man pages.

A well written manual page requires no additional tutorials, for they will be included in the text’s corpus.

Writing good documentation for one’s software is almost more important than writing the software itself; don’t force the user to have to run around the internet; be comprehensive in the manual.

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

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

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.

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

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.

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.

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"
    }

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

You can actually search for ' -l' (two spaces in front) and abuse the man layout engine to find the point at which the flag itself is defined. Makes the man pages a lot more useful in my opinion.

I agree with your point. There should be easier ways of doing some things in Unix. But since there are not (for some things, anyway, and I say this as a long-time Unix guy), sometimes, scripts can help. Here is one example by me:

m, a Unix shell utility to save cleaned-up man pages as text:

https://jugad2.blogspot.in/2017/03/m-unix-shell-utility-to-s...

This tiny script lets you generate man pages as cleaned-up text, saves them in a ~/man directory, and you can from then on, open them in your favorite text editor or even pager (less/more/pg/etc.) and view them. Created it out of real-life personal need some years ago, on a Unix system, but is still useful on Linux and other Unix-like systems today.

If your idea of what man is comes from using Linux, then you really haven't had a good exposure to what good documentation can be. Try Solaris or FreeBSD.

Indeed!

  man test | grep -- ‘ -e’

UNIX already has that as you can see. You just need to learn the target substrate you’re using.

> If I'm looking for option "-e" of the test command, why can't I do...

https://gist.github.com/alphapapa/3cba3ff196147ad42bac#file-...

    $ man test -e

           STRING1 != STRING2
                  the strings are not equal

           INTEGER1 -eq INTEGER2
                  INTEGER1 is equal to INTEGER2

           INTEGER1 -ge INTEGER2
                  INTEGER1 is greater than or equal to INTEGER2
    --

           INTEGER1 -ne INTEGER2
                  INTEGER1 is not equal to INTEGER2

           FILE1 -ef FILE2
                  FILE1 and FILE2 have the same device and inode numbers

           FILE1 -nt FILE2
                  FILE1 is newer (modification date) than FILE2
    --

           -d FILE
                  FILE exists and is a directory

           -e FILE
                  FILE exists

           -f FILE
                  FILE exists and is a regular file

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

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.

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.

Reply on news.ycombinator.com