5 ms·

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?

jasonlotito 13y ago
So you think they should be "written as part of real manpages?"
DanBC 13y ago
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
- andreasvc 13y ago
  What I meant is to submit patches to the upstream manpages, so that everyone benefits.
- JIghtuse 13y ago
  Thanks. English is not my native language. Of course, this can not be an excuse.
  - DanBC 13y ago
    No worries! I hope I was polite.
JIghtuse 13y ago
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.
userbinator 13y ago
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 http://cm.bell-labs.com/7thEdMan/bswv7.html
- dredmorbius 13y ago
  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.
hf 13y ago
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 https://news.ycombinator.com/item?id=7167835).

jasonlotito 13y ago

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

DanBC 13y ago

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

andreasvc 13y ago
What I meant is to submit patches to the upstream manpages, so that everyone benefits.
JIghtuse 13y ago
Thanks. English is not my native language. Of course, this can not be an excuse.
- DanBC 13y ago
  No worries! I hope I was polite.

JIghtuse 13y ago

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.

userbinator 13y ago

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 http://cm.bell-labs.com/7thEdMan/bswv7.html

dredmorbius 13y ago
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.

hf 13y ago

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 https://news.ycombinator.com/item?id=7167835).