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

101–110 of 169 posts

Re: Simplified and community-driven man pages

#101

Post by scaryclam »

coldtea wrote: post #94
_b8r0 wrote: post #84

Earlier quoted context omitted.

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'r…

> 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 itself. Adding that sort of howto clutter would make it a whole lot harder to use the pages properly. Why not leave man pages alone and just focus on info pages again (http://www.troubleshooters.com/linux/info.htm)? That was always the go-to for more verbose descriptions and has much more of a howto vibe about it.

Re: Simplified and community-driven man pages

#102

Post by np_tedious »

teamhappy wrote: post #97
coldtea wrote: post #92

Earlier quoted context omitted.

> So don't make it simplified, don't hail "community-driven", just go and start making suggested changes with the rest of your favourite OS community! Good luck with getting those accepted, when there's an established man page and for 30+ years simple examples like in tldr where frowned upon in almost all of them.

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 generally use this for a command I do not know so well.

Re: Simplified and community-driven man pages

#103

Post by jmfayard »

kleiba wrote: post #91
jmfayard wrote: post #77

Earlier quoted context omitted.

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

De gustibus non est disputandum. I've found javadocs enormously helpful when I was learning Java 20 years ago. But then again, I also like man pages and use them a lot. If I'm looking for option "-e" of the test command, here's what I would do: $ man test and then "/-e". Searching within a document is a commonly required skill in so many situations that I don't even think twice when applying it in man pages. Of cours…

That's full text search, not having directly the argument definition. If you search "-l" in "man ls", it will be only your 8th occurence.

Re: Simplified and community-driven man pages

#104

Post by webreac »

I think man pages should be bound to the code. For example chapter 2 should be part of kernel. When a new system call is added, the associated man page should be in the same commit. If a maintainer see a commit that would have an impact of man page without an update of man page, he can easily refuse the commit.

For me the first aims of man pages are to be complete and to be in sync with installed software. The orignal virtue of being terse was to be complete without requiring a lengthy description. If a man page is not complete, it has no excuse for being terse.

Re: Simplified and community-driven man pages

#105

Post by [deleted] »

_b8r0 wrote: post #84
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'r…

[deleted]

Re: Simplified and community-driven man pages

#106

Post by nerdponx »

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…

These community projects are great ways to test potential upstream changes before trying to make a bunch of upstream changes. The maintainer of the project doesn't have to field half-baked pull requests.

I think a bigger problem with man pages is not that they are badly written, it's that man itself is not user friendly:

1. I can't immediately jump to an entry for "-o", I have to use a search expression that might or might not work.

2. I can't reliably search for all references to "-o" from its definition.

3. I can't reliably jump to the definition of "-o" from any given reference.

4. I sure as hell can't search for "output" and easily find that "-o" is the option that controls the name of the output file.

5. There is no table of contents, and even if there were, there would be no way to link from an item in that table to its location in the manual.

HTML, for whatever it's deficiencies might be, is a far superior format for disseminating documentation. The Vim manual is pretty good too, due to the use of aggressive tagging and tight integration with those tags. Funny part is that manual pages can be written with semantic markup, but the semantic meaning is discarded once the manual pages rendered. It is totally backwards, and the world is in need of a better manual page renderer.

Re: Simplified and community-driven man pages

#107

Post by [deleted] »

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.

[deleted]

Re: Simplified and community-driven man pages

#108

Post by NelsonMinar »

IgorPartola wrote: post #26

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

info is a failed GNU experiment to replace man pages. I stated that strongly, but they've never caught on. It's too bad; GNU had a whole plan of improving Unix learnability with getopt, bash completion, info, etc. It's all sort of been useful but hasn't really changed the way people work.

Re: Simplified and community-driven man pages

#109

Post by dmitriid »

minusf wrote: post #69
jmfayard wrote: post #50

Earlier quoted context omitted.

A lot of us are "newbies" of "tar", "find", "[" and many others after years and years using *nix. According to the anti-usability mindset, this means that the users are wrong and ought to be changed, and not an hint that we should rethink how we write and consume documentation. Edit: the wording was angrier than it needed to be. A concrete example of a better documentation tool : https://kapeli.com/dash

dash is web documentation kept offline with limited search added on top of it. it's basically a browser window...

Which already makes it orders of magnitudes better than man

Re: Simplified and community-driven man pages

#110

Post by dmitriid »

onetruepretzel wrote: post #56
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 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
Post reply on HN