Show HN: manpages-tldr – short manpages with examples

* the survival of OP's labour is more likely; and

* one might use something like `eg`[0] to directly jump to the 'Examples' section.

[0] I gave a possible implementation below (https://news.ycombinator.com/item?id=7167835).

Note that you can still do this with manpages:

    man -Tps bash > /tmp/bash.ps

    man -Tps bash | ps2pdf - > /tmp/bash.pdf

How do you think, would I need to change license of a project if I want to push some examples to manpages?

People likely aren't going to use manpages-tldr for 4 page man pages. They may use it for gcc which is 17549 lines (without an examples section and examples are littered throughout the page, meaning you have to already know what you're looking for).

According to Wikipedia, man pages have been around since 1971[1]. Man pages were designed before a paradigm shift from systems oriented to user oriented design and are usually written in a manner that makes them easy to write, not easy to read. If you think about the first time you looked at man pages, they were likely difficult to look through and you just got used to it; that's what happened to me.

I would guess that most people would like examples of basic usage. The examples section of man pages is normally near the end but it's location isn't really standardized. I normally end up searching "/^[[:blank:]]*EXAMPLE" and if I don't find it I google it.

This doesn't mean that man pages are not useful when you know what you're looking for. They can be particularly useful for c code to supplement the headers themselves.

I think forcing man pages to be something that they are not isn't much better than having a bunch of nonstandard variants. I am not saying that the examples shouldn't be added, but man pages are very technical when most people probably want a layman example before the technical details.

[1] http://en.wikipedia.org/wiki/Man_page#History

You're arguing against the data. Care to continue doing so?

There are a few outliers, but really, the average page length is pretty low.

I'm running this right now, and what I'm getting is (5831 pages processed):

    mean:  3.9 pages
    median:  2 pages
    standard deviation:  11.06 pages

    5th %ile:  1
    25th %ile: 1
    75th %ile: 3
    95th %ile: 12

This is on a Debian GNU/Linux system with 3479 packages installed. I checked only English manpages under /usr/share/man (there are another dozen or so pages for openjdk under /usr/lib/jvm, max length 29 pages).

Obviously, mileage may vary.

Code:

    cd /usr/share/man
    time for f in $(find man[0-9] -type f -name \*.[0-9].gz); do echo -e "$f\t\c"; man $f 2>&1 | pr | grep '      Page [0-9][0-9]* *$' | tail -1 | sed 's/^.*\(Page \)//'; done

Compute statistical moments with your preferred analysis tool (I've got one I wrote for the purpose).

There are 68 manpages 37 pages or longer in length (2 standard deviations over mean). I see several shells (zshall, bash, tcsh), many perl utilities, and a few complex tools (mutt, openvpn, wireshark, busybox) among them. Pretty small count, actually.

Man pages were designed before a paradigm shift from systems oriented to user oriented design and are usually written in a manner that makes them easy to write, not easy to read.

While understanding a manpage's format is useful, ANY documentation which is "easy to write, not easy to read" is a bug.

As for alternatives to manual pages, I find the Linux Documentation Project's HOWTOs to be an excellent adjunct. GNU info pages, not so much.