Hacker News Reader

Comment by andreasvc | Hacker News Reader

Why can't people just improve manpages so that they include a readable abstract and examples instead of coming up with projects with cute names?

View on HN

Another way to think about this is, why can't manpages be written more concisely, so that the most common options and syntax are on the first page/"above the fold"?

Here is the 7th edition UNIX manual for comparison: http://cm.bell-labs.com/7thEdMan/bswv7.html

The printed output of the BSD 3.4 manuals for the first UNIX system I used (other than for playing BSD games as a kid) always had a certain fascination for me. Several large 3-ring binders comprising the sections of the manual, Postscript printed from their troff sources.

Note that you can still do this with manpages:

    man -Tps bash > /tmp/bash.ps

Or if you prefer PDF output:

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

... not that this addresses the content of the manpages, as you note. But at least you can decide on the format.

From the readme:

> This project aims to make fast-updated, practical and precise manpages with examples for everyday usage. Its idea based on similar projects, like bropages and tldr, but written as part of real manpages (mostly converted from Markdown with pandoc).

And if OP is reading this there's a couple of typos there.

Normally I don't care, but this is a do umentation project so it's important.

> Its idea based

Should be

> It's an idea based

What I meant is to submit patches to the upstream manpages, so that everyone benefits.

Thanks. English is not my native language. Of course, this can not be an excuse.

No worries! I hope I was polite.

Yes, as in that case

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

So you think they should be "written as part of real manpages?"

It is possible, but it takes a long way to approve and distribute manpages after changes. I like Michael Kerrisk for all his work. Manpages are great and I'm not trying to replace it, they have much more useful information.

Reply on news.ycombinator.com