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

11–20 of 169 posts

Re: Simplified and community-driven man pages

#11

Post by crag_hack »

harry8 wrote: post #4

I'm not following. The most useful thing on first read (and at other times) of man pages are the examples section. Frequently this section is pretty bare which is unfortunate. We should fix that. Yep with all of that. npm install a thing with multiple clients. Um, huh? Where did that come from? At best now we have 2 competing man page systems, one for the "complete" information and one for the examples section? This…

That's just a classic middlebrow dismissal comment.

This solution exists. Yours doesn't. This solution is also far more reasonable than yours. Your solution is to somehow land a manpage patch into every project while this is a single project that can be fleshed out by a single sufficiently motivated person.

Re: Simplified and community-driven man pages

#12

Post by exogen »

harry8 wrote: post #4

I'm not following. The most useful thing on first read (and at other times) of man pages are the examples section. Frequently this section is pretty bare which is unfortunate. We should fix that. Yep with all of that. npm install a thing with multiple clients. Um, huh? Where did that come from? At best now we have 2 competing man page systems, one for the "complete" information and one for the examples section? This…

The meat of the project is a crowdsourced database of examples for each program. So naturally there can be multiple clients for that database implemented in various ways. That doesn't seem too complicated. You choose and install one of them. Kind of like how POSIX systems have dozens of pagers, text editors, etc. to choose from.

It also seems way less crazy to crowdsource good examples than get each individual program's maintainer to add examples to the official man page (which could take decades to actually get onto people's systems, if they're even accepted), and then still require people to scroll down to the examples section.

Re: Simplified and community-driven man pages

#14

Post by reikonomusha »

menacingly wrote: post #13

I've always felt like it's a ding on my nerd credentials that I hate man pages. A lot of them feel deliberately opaque. 2-3 good examples are what joe blow is looking for when he types "man", and he rarely gets them.

This wasn’t always true, when software was less replaceable and felt more valuable. Part of this cake from the fact that software distribution was more difficult. If you ever have purchased a compiler for example you might find yourself interested in everything you can learn about it from the manual.

Now developers are trigger-happy Googlers looking for the single salient example atop StackOverflow answers.

Re: Simplified and community-driven man pages

#15

Post by begriffs »

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.

Re: Simplified and community-driven man pages

#16

Post by menacingly »

reikonomusha wrote: post #14
menacingly wrote: post #13

I've always felt like it's a ding on my nerd credentials that I hate man pages. A lot of them feel deliberately opaque. 2-3 good examples are what joe blow is looking for when he types "man", and he rarely gets them.

This wasn’t always true, when software was less replaceable and felt more valuable. Part of this cake from the fact that software distribution was more difficult. If you ever have purchased a compiler for example you might find yourself interested in everything you can learn about it from the manual. Now developers are trigger-happy Googlers looking for the single salient example atop StackOverflow answers.

Or, more likely, somewhere in the entire operation of a computer there exists a task or two in which we don't care to specialize.

Re: Simplified and community-driven man pages

#17

Post by chickenfries »

reikonomusha wrote: post #14
menacingly wrote: post #13

I've always felt like it's a ding on my nerd credentials that I hate man pages. A lot of them feel deliberately opaque. 2-3 good examples are what joe blow is looking for when he types "man", and he rarely gets them.

This wasn’t always true, when software was less replaceable and felt more valuable. Part of this cake from the fact that software distribution was more difficult. If you ever have purchased a compiler for example you might find yourself interested in everything you can learn about it from the manual. Now developers are trigger-happy Googlers looking for the single salient example atop StackOverflow answers.

The browser is a much nicer environment for consuming manuals than the terminal.

Re: Simplified and community-driven man pages

#18

Post by shmerl »

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, and as well allows extracting individual files fast. It's also compatible with xz itself.

Re: Simplified and community-driven man pages

#19

Post by apsdsm »

chickenfries wrote: post #17
reikonomusha wrote: post #14

Earlier quoted context omitted.

This wasn’t always true, when software was less replaceable and felt more valuable. Part of this cake from the fact that software distribution was more difficult. If you ever have purchased a compiler for example you might find yourself interested in everything you can learn about it from the manual. Now developers are trigger-happy Googlers looking for the single salient example atop StackOverflow answers.

The browser is a much nicer environment for consuming manuals than the terminal.

True, unless you're actively working in the terminal, in which case it's kind of a pain to switch to, I'm gonna say.

Re: Simplified and community-driven man pages

#20

Post by Spivak »

exogen wrote: post #12
harry8 wrote: post #4

I'm not following. The most useful thing on first read (and at other times) of man pages are the examples section. Frequently this section is pretty bare which is unfortunate. We should fix that. Yep with all of that. npm install a thing with multiple clients. Um, huh? Where did that come from? At best now we have 2 competing man page systems, one for the "complete" information and one for the examples section? This…

The meat of the project is a crowdsourced database of examples for each program. So naturally there can be multiple clients for that database implemented in various ways. That doesn't seem too complicated. You choose and install one of them. Kind of like how POSIX systems have dozens of pagers, text editors, etc. to choose from. It also seems way less crazy to crowdsource good examples than get each individual progra…

It's less crazy but more error prone. 3rd-party documentation has a tendency of being wrong and out of date quickly. It's not bad but it always needs to be taken with a grain of salt unless you really trust the maintainers of the docs.
Post reply on HN