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

41–50 of 169 posts

Re: Simplified and community-driven man pages

#41

Post by pletnes »

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…

I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway.

man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addition to man pages.

Re: Simplified and community-driven man pages

#42

Post by jlebar »

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.

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

Re: Simplified and community-driven man pages

#43

Post by aliahmed »

Are you looking for hacker? Contact for any hacking such as Facebook Hacking, Whatsapp Hacking, Instagram, Mobile Hacking, Increase credit score, removal of name from criminal record, removal of links from website. Recover Your email passwords, Hack into Bank/Company web site, etc,if you have any hacking contact: incfidelibus@gmail.com

Re: Simplified and community-driven man pages

#44

Post by [deleted] »

pletnes wrote: post #41
dfabulich wrote: post #36

Earlier quoted context omitted.

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…

I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway. man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addi…

[deleted]

Re: Simplified and community-driven man pages

#46

Post by whitef0x »

I find that what helps me the most are the '--help' commands, especially if it has multilevel support, like seen with the docker cli tool.

The problem with just providing examples is it doesn't always tell me what each argument does, especially if I have multiple arguments, making it seem like the tool works by having a 'magical' combination of arguments, instead of explaining what each argument does.

Re: Simplified and community-driven man pages

#47

Post by imiric »

shmerl wrote: post #27
gboudrias wrote: post #24

Earlier quoted context omitted.

By the way, at least for the ones I've tried, --extract now figures out the compression algorithm, so --use-compress-program is possibly redundant. With the cryptic short options it's only one letter, but I find it makes it easier to remember a distinct "4-letter scrabble" for creation versus a "3 letter scrabble" for extraction. (For the long options you save a lot of typing!)

tar wouldn't be able to figure out to use pixz instead of xz in this case just using implicit deduction. I don't really type those options, but use some simple wrapper scripts :) Something like pixzcompress / pixzextract. Scripts also take care to differentiate between directory and a single file.

If you're OK with wrapper scripts, take a look at dtrx[0]. It can extract many different formats, so assuming you have the tools already installed, extracting anything can be done with `dtrx `.

[0]: https://brettcsmith.org/2007/dtrx/

Re: Simplified and community-driven man pages

#48

Post by stinos »

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…

just called them "manuals"

I'd be more specific: man vs tldr/bro is almost like an appliance's user manual vs service manual. The latter is super in depth but usually doesn't explain in an understandable way how to actually use the tool. While the former does that, but once you're stuck it offers no deeper explanation and you're lost.

Re: Simplified and community-driven man pages

#50

Post by jmfayard »

pletnes wrote: post #41
dfabulich wrote: post #36

Earlier quoted context omitted.

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…

I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway. man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addi…

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

Post reply on HN