7 ms·
One thing I hate about man pages is that there are not enough examples. Sometimes feature is explained on five pages while simple one line example would explain
by dvh 8y ago
One thing I hate about man pages is that there are not enough examples. Sometimes feature is explained on five pages while simple one line example would explained it instantly. And at the end there should be 2-3 pages of examples at least, maybe even more.
- dijit 8y agoI find that this is something openBSD gets /really/ right. In general the man pages in BSD are phenomenal. What happened to ‘info’ pages. I hated it, but wasn’t that supposed to address these kinds of issues with examples?
- JoshMnem 8y agoInfo pages are still there. $ info grep
- arminiusreturns 8y agoInfo is much better than man, but keep in mind it's only covering gnu coreutils (which isn't a bad thing!)
- jwilk 8y agoHuh? grep is not part of coreutils.
- arminiusreturns 8y agoI know this is late but you are right. For some reason I thought info was only fore coreutils, but it seems I was wrong. I only ever used it for coreutils, but hey, thats good news to me!
- dijit 8y agoWhy is info better than man?
- kaushalmodi 8y agoBetter search and better organization of the document (TOC, index search, etc.). And reading/searching Info manuals is a lot more convenient in Emacs Info-mode.
- wrycoder 8y agoThe man page for gcc goes on and on. Try it. The info for gcc is a printed book, which is also accessible in the shell as hypertext (which predates html).
- sjmulder 8y agoIf you’re using a GNU system now you might be surprised by the quality of the BSD man pages, and documentation in general. Concise but still comprehensive, and plenty of examples. The tools (like man) aren’t really the problem here, the documentation itself is. (But it helps that the BSD folks show a bit more restraint wrt adding command line options.)
- tralarpa 8y agoI have just compared the man pages for Linux and FreeBSD, but the result is not really clear: Example provided on the FreeBSD man page of cut. Examples provided on the Linux man page of xargs. More examples provided on the Linux man page of find.
- sjmulder 8y agoI find the cut man page (looking at the OpenBSD one) very clear. It's just 62 lines (fits on a screen), has only 5 flags and the 2 examples clearly show how the tool is used. The xargs man page is ought to have some examples, I agree. The find manual is lengthy (as it has a bunch of options) but not excessively so and it also has a good bunch of examples. Edit: it also helps to be familiar with the pager, like using the search feature (hit / , n, n, Shift+n, ...) and the jump keys (G and g).
- zuppy 8y agotldr tries to fix that: https://tldr.sh https://tldr.sh
- yoz-y 8y agoEver since I have discovered tldr i've been using man pages less and less.
- dotancohen 8y agoWhen viewing man pages, you are using less by default. lrf, guvf vf n cha
- erisds 8y agoAlso a big fan of tldr :) But love the idea of writing my own.
- Annatar 8y agoNot enough examples is only in GNU/Linux; the BSD’s and illumos-based operating systems have plenty of examples. Especially illumos, since they enforce a rule that no component may be integrated without a comprehensive manual page and since they come from Solaris, most of the documentation was written by a dedicated department of professional technical writers working with the engineers to document their work in a systematic fashion.
- ptman 8y agoperldoc begins with examples by convention. No need to /EXA See e.g. https://metacpan.org/pod/release/PHRED/Archive-Zip-1.62/lib/Archive/Zip.pm https://metacpan.org/pod/release/PHRED/Archive-Zip-1.62/lib/...
- philbarr 8y agoThose who can, do Those who can't, teach Those who can't teach, write Those who can't write, write man pages
- tpfour 8y agoAnd those who believe in this aphorism have never did, taught or written :)
- TremendousJudge 8y agohonestly, not having a man page would be better than half of the man pages out there
- jgtrosh 8y agoHaving benefited tremendously from manpages I believe they're absolutely worth existing, whatever manpage seemed insufficient to you.
- deviationblue 8y agoThose who can, do. Those who can't, become product managers.
- simplify 8y agoThis is a pet peeve of mine. Teachers are not somehow inferior to those who do. It's a completely different skill set that actually helps you "do" better.
- JoeAltmaier 8y agoExactly. In sport we respect coaches for their particular skills. But somehow teachers get joked about.
- dcole2929 8y agoSure we respect coaches, but we also still in every sport pay them significantly less than the pros they ostensibly lead. I personally value both coaches and teachers but it's very clear that we as a people have decided that ability to do is more valuable than the ability to teach others.
- ddevault 8y agoMan pages are a community project. Send patches!
- oblio 8y agoWhile this is laudable, how many GNU projects, especially, don't use an archaic development/contribution process? I don't want to have to register on a mailing list and prepare patches. This is an honest question. Friction and barriers to entry reduce contributions.
- S-E-P 8y agoI second this, there's so much wasted work, and because that old contribution process there's no guarantee that even an absolutely fantastic patch, like a better man page for example. Will ever see the light of day. I've tried in the past, it doesn't work out (not man pages, but I was fixing a bug and yeah, three, four submissions was enough for me to quit trying)
- jwilk 8y agoMore importantly, many (most?) GNU projects don't care about man pages: https://www.gnu.org/prep/standards/html_node/Man-Pages.html https://www.gnu.org/prep/standards/html_node/Man-Pages.html
- jplayer01 8y agoThis encapsulates one of my biggest gripes with Linux. A lack of appreciation for adequate/good documentation. > The time you spend on the man page is time taken away from more useful work. Making sure your users know how your program works, how to use it and what it's capable of seems incredibly important and useful to me. If it weren't for Arch Linux's fantastic focus on documenting everything to do with Linux, I wouldn't be using Linux at all.
- owaty 8y agoThat page is specific to man pages, not to documentation in general. See https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm...
- swebs 8y agoSounds like you want bro pages http://bropages.org/ http://bropages.org/
- banku_brougham 8y agoI don't think the use case is the same. um is for saving and viewing personal notes about usage, bropages is a common set of examples submitted by the wider community. This other response says it better: https://news.ycombinator.com/item?id=17801788 https://news.ycombinator.com/item?id=17801788
- appleflaxen 8y agothat's what bro does by default; you only push an example to the community explicitly.
- overcast 8y agoAttempting to read nix man pages, always felt like I was alone in learning best from examples. Documentation in any form without examples is always difficult for me to sort through.