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

111–120 of 169 posts

Re: Simplified and community-driven man pages

#111

Post by PapstJL4U »

notatoad wrote: post #23
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…

a "manual" is not inherently restricted to being a reference. there's no reason a manpage shouldn't include a quick-start guide as well.

Yeah. It looks like some people argue against each other for no reason. I am pretty sure in many fields of work a manual actually explains how to do so me thing. The infamous IKEA manual is an how-to, the last car manuals all had how-tos include: how to change radio station, how to change oil,...

Is their ever a moment, that some picks up a manual and doesn't want to know how to do something?

Re: Simplified and community-driven man pages

#112

Post by yjftsjthsd-h »

np_tedious wrote: post #102
teamhappy wrote: post #97

Earlier quoted context omitted.

https://tldr.ostera.io/tar https://man.openbsd.org/tar#EXAMPLES What they're covering is just the examples section of a traditional man page. What makes you think people wouldn't merge these?

It's a fundamentally different goal / structure. `man` documents every last flag, and I generally use it for a command I know decently but need to dig into particulars. It goes to a scrollable page like `less` which is important bc it's total size spans several pages. `tldr` is shows the 3-4 most common use cases for a command, and puts it right to stdout more like `cat` so you can refer to it as you type along. I'd…

And why could that not go in the example section of the manual?

Re: Simplified and community-driven man pages

#113

Post by coldtea »

scaryclam wrote: post #101
coldtea wrote: post #94

Earlier quoted context omitted.

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

Re: Simplified and community-driven man pages

#115

Post by begriffs »

dmitriid wrote: post #110
onetruepretzel wrote: post #56

Earlier quoted context omitted.

I must admit I'm not a fan of this. I feel like the work could go towards submitting patches to the man pages. The MAN page layout [0] allows for an EXAMPLES section which serves this purpose. Great effort in creating this tool but I think it's replicating functionality already provided by the man pages. I've submitted patches for MAN pages for GNU tools in the past and the creators are very receptive to updates. [0]…

Yup, and the examples section is usually last, with no possibility to jump directly to it

You can jump to it by typing /EXAMPLES

Or if that seems like a lot of keystrokes, /EX will probably jump to what you want most of the time too.

Re: Simplified and community-driven man pages

#116

Post by asveikau »

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.

Why would you want a manpage that doesn't have the structure of a manpage? If every other manpage has one structure, you want yours to have another? What's special about yours?

The consistency is not an accident and my personal experience is that the format works well.

Re: Simplified and community-driven man pages

#117

Post by fiddlerwoaroof »

jlebar wrote: post #42
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.

> BSDs tend to have excellent documentation as do some individual projects (git) Should we really point to git as an example of great documentation? I mean, this exists and has to have a giant banner at the top saying "these are NOT REAL": https://git-man-page-generator.lokaltog.net/

Yeah, I use the git manpages all the time when I need to do something unusual and have generally found them to be very helpful, but they aren’t written for people who don’t know how to use git.

Re: Simplified and community-driven man pages

#118

Post by Sir_Cmpwn »

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…

You hit the nail on the head. If you want simple examples, send patches to your maintainers extending (or adding) the EXAMPLES section of the manual instead of looking to a project like tdlr pages.

Re: Simplified and community-driven man pages

#119

Post by detaro »

asveikau wrote: post #116
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.

Why would you want a manpage that doesn't have the structure of a manpage? If every other manpage has one structure, you want yours to have another? What's special about yours? The consistency is not an accident and my personal experience is that the format works well.

The point is exactly that people do not want something like a man page, so they make their own thing that's not like a man page, and the suggestion "go contribute to manpages instead" isn't a good one, because it would mean making bad man pages (or not fixing the issue people have). If aspects are useful for the man pages (e.g. to make better examples sections), they can still be pulled out and added there as well.

Re: Simplified and community-driven man pages

#120

Post by jwilk »

mjw1007 wrote: post #80
jwilk wrote: post #75

Earlier quoted context omitted.

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

"i" works also in stand-alone info. I was hoping pinfo can do this too, but I can't see such functionality. :(
Post reply on HN