Lovely.
I just wrote a bash client. It uses curl to download the page, pandoc to convert md to html and lynx to display the html page.
Simplified and community-driven man pages
21–30 of 169 posts
Re: Simplified and community-driven man pages
#22When people think of manpages, they tend to think of Linux. At least that's what I thought of, until a few months ago when I discovered OpenBSD. Their manual is concise and coherent, unlike the rambling hodgepodge on Linux. Of course it's always nice to have a bunch of curated examples like TLDR or "bro" pages, but just wanted to point out that the manpage situation isn't universally grim.
By Linux do you mean GNU? Because those are the wordiest and least straightforward. BSDs tend to have excellent documentation as do some individual projects (git), while others (OpenSSL) leave something to be desired. And of course GNU tar is a special little hell. But Linux just happens to run on a GNU userland most of the time so you get those a lot.
Re: Simplified and community-driven man pages
#23The main thing about man pages is that it is a "manual": reference material for people who already know the basics. If you are just getting started, don't read the man pages, but read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books. Those will generally be tailored to beginners, including features such as discussions of unifying themes between different commands, historical references and…
a "manual" is not inherently restricted to being a reference. there's no reason a manpage shouldn't include a quick-start guide as well.
Re: Simplified and community-driven man pages
#24tar makes a lot more sense if you use long options instead of completely cryptic short ones. tar command I've been using recently (scripted of course): To compress: tar --create --verbose --use-compress-program="pixz" --file foo.tar.xz --directory . To extract: tar --extract --verbose --use-compress-program "pixz -d" --file foo.tar.xz Unlike bz2 or xz, pixz it uses all CPU cores both for compression and decompression…
By the way, at least for the ones I've tried, --extract now figures out the compression algorithm, so --use-compress-program is possibly redundant.
With the cryptic short options it's only one letter, but I find it makes it easier to remember a distinct "4-letter scrabble" for creation versus a "3 letter scrabble" for extraction.
(For the long options you save a lot of typing!)
Re: Simplified and community-driven man pages
#25This is a very interesting project. Years ago when I wanted to learn how to use Linux, my friend who was a system admin at the time just told me to read Man Pages. It was so overwhelming and confusing to say the least, it made me give up on Linux for a long while. Times have changed and I will definitely love to contribute as well as recommend this project.
Heh. Should have told you to go read the FreeBSD manual. That’s the first OS that made sense to me because of it. I actually ended up translating parts of it to Russian because I enjoyed it so much.
NetBSD was the first thing I got running reliably on my ancient hardware. Linux eventually worked but it was process. And man pages don’t explain what the system does at all.
Re: Simplified and community-driven man pages
#26Anyone ever get anything useful out of info pages (vs man pages)? I never quite got what their deal was.
Re: Simplified and community-driven man pages
#27tar makes a lot more sense if you use long options instead of completely cryptic short ones. tar command I've been using recently (scripted of course): To compress: tar --create --verbose --use-compress-program="pixz" --file foo.tar.xz --directory . To extract: tar --extract --verbose --use-compress-program "pixz -d" --file foo.tar.xz Unlike bz2 or xz, pixz it uses all CPU cores both for compression and decompression…
By the way, at least for the ones I've tried, --extract now figures out the compression algorithm, so --use-compress-program is possibly redundant. With the cryptic short options it's only one letter, but I find it makes it easier to remember a distinct "4-letter scrabble" for creation versus a "3 letter scrabble" for extraction. (For the long options you save a lot of typing!)
tar wouldn't be able to figure out to use pixz instead of xz in this case just using implicit deduction.
I don't really type those options, but use some simple wrapper scripts :)
Something like pixzcompress / pixzextract. Scripts also take care to differentiate between directory and a single file.
Re: Simplified and community-driven man pages
#28This is a cool idea, but I’ve seen several similar tools and for some reason have never managed to integrate them into my workflow, so I still just google “scp examples” or use my shell history to find previous times when I figured out how to use a command.
Re: Simplified and community-driven man pages
#29The main thing about man pages is that it is a "manual": reference material for people who already know the basics. If you are just getting started, don't read the man pages, but read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books. Those will generally be tailored to beginners, including features such as discussions of unifying themes between different commands, historical references and…
Usually it’s just me trying to do some task and not caring to ever “learn the command” with any depth (because I don’t use it enough for that to be worthwhile). That’s why examples are great. I can probably usually just scan the examples and quickly recognize the one that does the thing I want to do.
Re: Simplified and community-driven man pages
#30I was lucky to first be introduced to man pages by someone who often just called them "manuals" and (to my best recollection) explained them by telling me "Manuals are to be read, top to bottom, contemplated, and maybe read again, before you act."
Thus I was never under the delusion that man pages were, or should strive to be, How-To's of some sort.
This TLDR tool definitely needs to exist, but in conjunction with man pages, not as a replacement. Manuals should continue to exist in a form that explores and explains the depths of a utility or command in whatever length that might require. I will make adequate use of both.