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

81–90 of 169 posts

Re: Simplified and community-driven man pages

#81

Post by rollthehard6 »

JdeBP wrote: post #59
pjmlp wrote: post #51

Earlier quoted context omitted.

Manpages are UNIX thing, and I can tell you that GNU ones are much better than what commercial UNIXes used to be like.

And as someone who, even nowadays, still points to the commercial manual pages for SCO Unix, HP/UX, AIX, Solaris, and suchlike, oftentimes for things that the GNU and BSD manual pages simply do not cover, I can tell you that you are quite wrong. * https://news.ycombinator.com/item?id=15541694 * https://unix.stackexchange.com/a/406545/5132 * https://unix.stackexchange.com/a/196471/5132 Here are the HP-UX, AIX, Solaris…

This, so much this. Having only transitioned into RHEL from Solaris in the latter 1/4 of my career, I still hark back to Solaris man pages and to this day, on Linux I will do -

man foo

/EXAMPLES

And frequently find what I find, if there are any at all, very lacking compared to Solaris.

I have often thought I and others who complain about this should get involved in working on these man pages and improve this situation.

Re: Simplified and community-driven man pages

#82

Post by DC-3 »

If anyone doesn't want to install `npm` and wants to know what client to use, the Haskell/Stack one is nice. It's pretty snappy and has a sane syntax † and data directory (~/.tldr/).

† Unlike `tldr.py`, which requires you to do `tldr find ` instead of `tldr `

Re: Simplified and community-driven man pages

#83

Post by boomlinde »

detaro wrote: post #78
carlosrg wrote: post #74

Earlier quoted context omitted.

"Community-driven" doesn't mean mindlessly accepting every patch that is submitted. Respecting the well-known structure of man pages is a good thing.

Most of the criticism here is exactly about how people do not like the structure of man pages for this use case. If the parent suggests contributing to man pages as a fix for these issues, "Respecting the well-known structure of man pages" goes counter to that goal and suggests that solving this issue outside of man pages actually is the better solution.

Many of these pages would make fine EXAMPLES sections for the corresponding man pages without compromising the overall structure.

Re: Simplified and community-driven man pages

#84

Post by _b8r0 »

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're looking for is in an info manual or somewhere like /usr/share/doc/.

Re: Simplified and community-driven man pages

#85

Post by JdeBP »

more-coffee wrote: post #79
carlosrg wrote: post #72

I don't get the point of this. Man pages already have a "description" section where they give a simplified explanation of the tool, an "examples" section where they give typical usage, etc.

"Description", yes, "Examples", not always; https://linux.die.net/man/1/sed https://linux.die.net/man/1/grep I think the tldr client can be immensely helpful as a quick cheatsheet in daily operations, whereas manpages will remain to be go-to references for those with time and patience to learn all about the tool in question.

Only looking at GNU manual pages gives you a wildly incorrect impression of things.

* https://news.ycombinator.com/item?id=15780296

Try looking at manual pages that are not GNU.

* http://nixdoc.net/man-pages/HP-UX/man1/sed.1.html#EXAMPLES

* https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.i...

* https://www.freebsd.org/cgi/man.cgi?query=sed#EXAMPLES

* http://man.openbsd.org/sed#EXAMPLES

Re: Simplified and community-driven man pages

#86

Post by yhbgffvv »

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…

TFA uses a “NodeJS” “client” and its members nerd out on “Gitter”. I’m not sure what the hell any of that hipster bullshit means, but to people of that ilk, if it’s not on GitHub it does not exist.

Re: Simplified and community-driven man pages

#87

Post by pjmlp »

JdeBP wrote: post #59
pjmlp wrote: post #51

Earlier quoted context omitted.

Manpages are UNIX thing, and I can tell you that GNU ones are much better than what commercial UNIXes used to be like.

And as someone who, even nowadays, still points to the commercial manual pages for SCO Unix, HP/UX, AIX, Solaris, and suchlike, oftentimes for things that the GNU and BSD manual pages simply do not cover, I can tell you that you are quite wrong. * https://news.ycombinator.com/item?id=15541694 * https://unix.stackexchange.com/a/406545/5132 * https://unix.stackexchange.com/a/196471/5132 Here are the HP-UX, AIX, Solaris…

Well, that was my memory going back to 2000. It has been a while since I bothered to look into them.

I remember having to go into the official documentation available on the HP, IBM and Sun web sites to find usable information, instead of just going through man pages.

Re: Simplified and community-driven man pages

#88

Post by JdeBP »

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…

Discussion on this page at https://news.ycombinator.com/item?id=15779457 has already touched upon this.

Re: Simplified and community-driven man pages

#89

Post by menacingly »

ape4 wrote: post #70
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.

Of course, many man pages have an EXAMPLES section. You can search for it with `/EXAMPLES` when viewing the man page. On my Linux box: zgrep EXAMPLE /usr/share/man/man1/* | wc -l Gives 897

and:

  zgrep -L EXAMPLE /usr/share/man/man1/* | wc -l
Gives

  1629
Post reply on HN