Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Simplified and community-driven man pages

tldr.sh

Post reply on HN
Print view View original

131–140 of 169 posts

Re: Simplified and community-driven man pages

#131

Post by nathyong »

jmfayard wrote: post #103
kleiba wrote: post #91

Earlier quoted context omitted.

De gustibus non est disputandum. I've found javadocs enormously helpful when I was learning Java 20 years ago. But then again, I also like man pages and use them a lot. If I'm looking for option "-e" of the test command, here's what I would do: $ man test and then "/-e". Searching within a document is a commonly required skill in so many situations that I don't even think twice when applying it in man pages. Of cours…

That's full text search, not having directly the argument definition. If you search "-l" in "man ls", it will be only your 8th occurence.

You can actually search for ' -l' (two spaces in front) and abuse the man layout engine to find the point at which the flag itself is defined. Makes the man pages a lot more useful in my opinion.

Re: Simplified and community-driven man pages

#132

Post by _b8r0 »

coldtea wrote: post #94
_b8r0 wrote: post #84

Earlier quoted context omitted.

People who complain about man pages tend not to understand man pages. Man pages aren't howto documentations. They're very specifically designed to document the different components of a command, call or configuration file. OP is absolutely spot on about man pages being community driven. At least half the time someone complains to me about a man page, the man page is the wrong place to look. Usually, the answer they'r…

> People who complain about man pages tend not to understand man pages. That's their very issue with them. > Man pages aren't howto documentations. They're very specifically designed to document the different components of a command, call or configuration file. Then people who designed man pages didn't understand what the users want first and foremost: howto examples. Besides, whether they document "the different com…

I pointed you directly at the correct sources of documentation: info pages (for most GNU software) and /usr/share/docs. These are the places where howtos belong, not man pages.

The issue isn't with man pages themselves. The issue is with the expectations sites, tutorials and users themselves set for man pages.

Re: Simplified and community-driven man pages

#133

Post by _b8r0 »

coldtea wrote: post #113
scaryclam wrote: post #101

Earlier quoted context omitted.

I don't think it's fair to say that the originators of man pages didn't understand what their users were looking for. In most cases, the authors are the users, and when they were first created, that was pretty much the only user base they had. Man pages are manual pages, not howto pages. If I'm looking at a man page, it's pretty much always because I want to look up one of the options, not how to use the command itse…

> Man pages are manual pages, not howto pages. Isn't that a made-up distinction though? Who said manuals can't have representative examples for how to do certain tasks? Product manuals (including software product manuals) almost always do. They don't just enumerate features and flags.

> Who said manuals can't have representative examples for how to do certain tasks?

Dennis Ritchie defined what goes into the manual in the 3rd edition of UNIX, at the behest of Doug McEllroy. Ken Thompson also did some work on man pages, and I believe Lorinda Cherry was involved too. As I understand it (and I could be wrong though) the terseness of man pages was Ritchie's design, with input from Thompson.

Re: Simplified and community-driven man pages

#134

Post by [deleted] »

gboudrias wrote: post #24
shmerl wrote: post #18

tar 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!)

[deleted]

Re: Simplified and community-driven man pages

#135

Post by digi_owl »

imiric wrote: post #47
shmerl wrote: post #27

Earlier quoted context omitted.

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.

If you're OK with wrapper scripts, take a look at dtrx[0]. It can extract many different formats, so assuming you have the tools already installed, extracting anything can be done with `dtrx `. [0]: https://brettcsmith.org/2007/dtrx/

There is also atool.

http://www.nongnu.org/atool/

Re: Simplified and community-driven man pages

#137

Post by digi_owl »

While reading all the complaints about the man page layout, i find myself thinking that it likely made perfect sense back when teletypes were the predominant terminal.

look up something via man, tear off the output, and put it next to you. Maybe collect the most used ones in a binder to bring with next time.

Then again, man man may be "enlightening"...

Re: Simplified and community-driven man pages

#138

Post by bigger_cheese »

begriffs wrote: post #15

When 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.

The man pages for Linux kernel internals and syscalls are pretty good stuff like, inotify, procfs etc all have really good detailed man pages. The userland stuff is a different story. I think it is because BSD doesn't distinguish userland from kernel they are all shipped in the same package so manual pages are probably kept more consistent. Linux uses stuff like GNU etc for a lot of userland tools so it is more of a mixed bag different community different developers etc.

Re: Simplified and community-driven man pages

#139

Post by Qwertious »

_b8r0 wrote: post #84
PaulRobinson wrote: post #64

Hilariously, ITT are lots of comments saying that man is awful, in response to a pot about a "simplified and community-driven" alternative. Breaking news: man pages are community-driven already. You can make them better in your distro of choice. The BSD projects are a little better IMHO at this than Linux because each project has a dedicated team trying to raise the bar and make their docs better than the next distro…

People who complain about man pages tend not to understand man pages. Man pages aren't howto documentations. They're very specifically designed to document the different components of a command, call or configuration file. OP is absolutely spot on about man pages being community driven. At least half the time someone complains to me about a man page, the man page is the wrong place to look. Usually, the answer they'r…

"People who complain about man pages tend not to understand man pages."

There could not be a more valid complaint. If the man pages aren't understandable, what program is supposed to explain them?

Re: Simplified and community-driven man pages

#140

Post by Qwertious »

baddox wrote: post #31
baddox wrote: post #29

Earlier quoted context omitted.

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.

Of course, sometimes this attitude of mine is a problem. The most obvious example for me is git, which I use nearly every day, but still have an embarrassingly shallow understanding of. Any time something “goes wrong” I’m googling for a magic command to fix it, or resorting to crude measures like copying the whole repo directory and resetting hard.

>The most obvious example for me is git, which I use nearly every day, but still have an embarrassingly shallow understanding of. Any time something “goes wrong” I’m googling for a magic command to fix it,

This is basically the reason I use Mercurial. It actually makes sense without getting a bloody degree in "how to use your DVCS", and the help is quite nice, and not a godawful clusterfuck like some popular DCVSes that were developed by developers of major FOSS kernels circa 2005.

Post reply on HN