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

31–40 of 169 posts

Re: Simplified and community-driven man pages

#31

Post by baddox »

baddox wrote: post #29
kccqzy wrote: post #6

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

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.

Re: Simplified and community-driven man pages

#34

Post by begriffs »

IgorPartola wrote: post #22
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.

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.

That's a good distinction. Yeah, GNU.

Re: Simplified and community-driven man pages

#35

Post by patrec »

IgorPartola wrote: post #26

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

A manpage is a glorified README. An info page is a non-horrendous version of a html manual. So to see the appeal, don't compare `man cp` with `info cp`, try some more substantial manual like the emacs manual or python's documentation. Also, emacs is a much better info reader than the standalone program.

Info pages are at least an order of magnitude more efficient to navigate than the html documentation that has supplanted them. All the following are fast and a single keypress:

- regexp (s)earch (not just the current page, the whole document)

- hierarchical navigation ((u)p, (n)ext, (p)revious)

- jump to any (i)ndex topic

- jump between links/sections (by position: tab, shift-tab, by na(m)e)

The main shortcoming of info is no support for styling (or graphics) whatsoever, but if you're used to its efficiency using a mix of googling and clicking to navigate the html equivalent is profoundly frustrating.

The closest modern equivalent I know of is Dash.

Re: Simplified and community-driven man pages

#36

Post by dfabulich »

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 fine, and then a list of options in alphabetical order which is almost always the least useful ordering. Categorize the parameters. Juxtapose confusingly similar options.

And only then do we get any examples, if any. The examples should have come first, in the synopsis.

There's nothing inherently wrong with man pages, but nobody has to follow this tradition. Put real examples in your synopsis and manually sort your options; you'll have a man page that's 20x better than most.

Re: Simplified and community-driven man pages

#37

Post by dfabulich »

tnoerlcnt34 wrote: post #8
kccqzy wrote: post #6

The 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…

Sure, but what usually happens is you sit down at a Unix command line for the first time and have no idea what to do. You ask someone (after seeing that `help` does nothing useful), and they tell you "use 'man' instead of 'help'". And you have no idea why, but you try it and it kind of helps and is better than nothing. You don't have any idea you should `read one of the many "Getting Started" or "Quick Guide" or "Beg…

I think this is how it used to be, but now people just Google their problems, and typically they get Stack Overflow as a result.

Earlier this year, they announced that they have helped over one million developers to exit vim, for example. https://stackoverflow.blog/2017/05/23/stack-overflow-helping...

In my experience, the top-rated SO answer is typically better than the man page, because it answers the specific question I have, rather than listing all of the options in alphabetical order, forcing me to search the page itself for the information I really wanted.

Re: Simplified and community-driven man pages

#38

Post by wichert »

IgorPartola wrote: post #22
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.

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. I'm not sure if the use of Texinfo is still a requirement for GNU projects.

The verbosity of the generated man pages for GNU software probably did influence a lot of non-GNU Linux software.

Re: Simplified and community-driven man pages

#40

Post by jap »

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…

I've integrated TLDR content into online man pages if you'd like to see both in one place. For example: https://www.mankier.com/1/grep
Post reply on HN