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

71–80 of 169 posts

Re: Simplified and community-driven man pages

#71

Post by jwilk »

wichert wrote: post #38
IgorPartola wrote: post #22

Earlier quoted context omitted.

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.

On many Linux systems there are likely to be more non-GNU commands than GNU commands, so I'm not sure your argument fully works here. GNU historically never made man pages: they used Texinfo for documentation, possibly combined with a tool to convert Texinfo to man pages. That shows in the result: an entire manual all joined together in a single unreadably long manual page. The bash man page is a nice example of that…

At least in bash 4.4, the manpage and the info page are two different documents.

Many GNU manpages are generated with help2man, which causes the opposite problem, i.e. they are too terse. (Also, their typographical quality is often low.)

Re: Simplified and community-driven man pages

#73

Post by JdeBP »

apsdsm wrote: post #19
chickenfries wrote: post #17

Earlier quoted context omitted.

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.

Nonetheless, it was the reasoning that underpinned Daniel Bernstein's slashdoc idea from the turn of the century.

* https://cr.yp.to/slashdoc.html

Re: Simplified and community-driven man pages

#74

Post by carlosrg »

detaro wrote: post #68
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…

Have you successfully convinced any distro to deviate from the normal structure of a man page? If not, I don't believe your suggestion is very realistic.

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

Re: Simplified and community-driven man pages

#75

Post by jwilk »

mjw1007 wrote: post #67
IgorPartola wrote: post #26

Anyone ever get anything useful out of info pages (vs man pages)? I never quite got what their deal was.

As far as the content and organisation goes, they're basically doing everything right that manpages do wrong. They separate tutorial and reference documentation, don't collapse under their own weight when they get large, and have a way to find the documentation for a particular short option. The original standalone terminal reader was pretty poor, though. These days use pinfo or the html version if you're not an emac…

> have a way to find the documentation for a particular short option

How?

Re: Simplified and community-driven man pages

#76

Post by mjw1007 »

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…

Note that the GNU ls manpage is just `ls --help` in manpage format, with a "SEE ALSO" section at the bottom which tells you where the real documentation is.

Re: Simplified and community-driven man pages

#77

Post by jmfayard »

dfabulich wrote: post #36
chao- wrote: post #30

I 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 ma…

The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is…

Man is like javadocs: useless unless you already know what you are doing, and then usually a wordy paraphrase of the method signature :(

Even as a reference manual, man is bad though.

If I'm looking for option "-e" of the test command, why can't I do

    $ man test -e
     -e file       True if file exists (regardless of type).
That seems more efficient, more unix-friendly and not too much to ask.

I get this is an historical tool that only cares about displaying the output of nroff. We would need a new tool with more empathy ($ woman? )

Re: Simplified and community-driven man pages

#78

Post by detaro »

carlosrg wrote: post #74
detaro wrote: post #68

Earlier quoted context omitted.

Have you successfully convinced any distro to deviate from the normal structure of a man page? If not, I don't believe your suggestion is very realistic.

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

Re: Simplified and community-driven man pages

#79

Post by more-coffee »

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.

Re: Simplified and community-driven man pages

#80

Post by mjw1007 »

jwilk wrote: post #75
mjw1007 wrote: post #67

Earlier quoted context omitted.

As far as the content and organisation goes, they're basically doing everything right that manpages do wrong. They separate tutorial and reference documentation, don't collapse under their own weight when they get large, and have a way to find the documentation for a particular short option. The original standalone terminal reader was pretty poor, though. These days use pinfo or the html version if you're not an emac…

> have a way to find the documentation for a particular short option How?

There's an index, usually a separate one for command-line options.

For example in the sed info pages it's under "Command and Option Index" at the bottom of the top-level menu.

And, at least in the emacs viewer, there's a keyboard shortcut so you can just type something like « i - n » to see the docs for -n.

Post reply on HN