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

51–60 of 169 posts

Re: Simplified and community-driven man pages

#51

Post by pjmlp »

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.

Manpages are UNIX thing, and I can tell you that GNU ones are much better than what commercial UNIXes used to be like.

Re: Simplified and community-driven man pages

#52

Post by jmfayard »

Spivak wrote: post #20
exogen wrote: post #12

Earlier quoted context omitted.

The meat of the project is a crowdsourced database of examples for each program. So naturally there can be multiple clients for that database implemented in various ways. That doesn't seem too complicated. You choose and install one of them. Kind of like how POSIX systems have dozens of pagers, text editors, etc. to choose from. It also seems way less crazy to crowdsource good examples than get each individual progra…

It's less crazy but more error prone. 3rd-party documentation has a tendency of being wrong and out of date quickly. It's not bad but it always needs to be taken with a grain of salt unless you really trust the maintainers of the docs.

That would be a very good point if this was documenting javascript frameworks, but I doubt the usages of "tar" and "find" change too often.

Re: Simplified and community-driven man pages

#53

Post by microcolonel »

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…

> not even as a reference

How are you supposed to write reference documentation without a section for describing the options which can be referred to by option name?

> The examples should have come first, in the synopsis.

Type with me: / E X A . If anything, perhaps the first manual a man user should read is the manual for their default pager, usually LESS(1).

There are good and bad manpages, but I don't see how the format is truly deficient. Some very complex commands have separate sections for the most and least common options (or groups of related options, if there are subcommands or similar).

Re: Simplified and community-driven man pages

#54

Post by JdeBP »

IgorPartola wrote: post #25
Xunxi wrote: post #2

This is a very interesting project. Years ago when I wanted to learn how to use Linux, my friend who was a system admin at the time just told me to read Man Pages. It was so overwhelming and confusing to say the least, it made me give up on Linux for a long while. Times have changed and I will definitely love to contribute as well as recommend this project.

Heh. Should have told you to go read the FreeBSD manual. That’s the first OS that made sense to me because of it. I actually ended up translating parts of it to Russian because I enjoyed it so much. NetBSD was the first thing I got running reliably on my ancient hardware. Linux eventually worked but it was process. And man pages don’t explain what the system does at all.

Of course, as people have pointed out already, a user manual is not a tutorial, and the two are distinct and complementary. This is something that one finds in many spheres, from Microsoft operating systems to Linux ones.

One of the things that MSDN and TechNet doco does is have both "X reference" and "using X" sections. Manual pages are reference doco, in this way of organizing things. The BSD worlds put the "using X" doco into what are often called "handbooks" or "guides".

* NetBSD Guide: https://netbsd.org/docs/guide/en/

* FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html

* DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/

* TrueOS User Guide: https://www.trueos.org/handbook/trueos.html

* PC-BSD User Guide: http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html (viewable off-line directly in both PDF and HTML forms in /usr/local/share/pcbsd/doc/)

Some parts of the Linux world do the same. upstart had the Upstart Cookbook for example:

* http://upstart.ubuntu.com/cookbook/

My nosh toolset comes with user manual pages for the individual commands, written in DocBook XML as I just mentioned in https://news.ycombinator.com/item?id=15779321 , and a nosh Guide.

* http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html

* http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-soc...

* http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatshe...

* http://jdebp.eu./Softwares/nosh/guide.html

The Linux Documentation Project was supposed to contain a wealth of this stuff, but large parts of it are seemingly moribund, and incomplete after decades or woefully outdated. Wikibooks tried to take up the slack with an "anyone can edit" Guide to Unix and a Linux Guide:

* https://en.wikibooks.org/wiki/Guide_to_Unix

* https://en.wikibooks.org/wiki/Linux_Guide

For examples and doco that works from the basis of what one usually wants to do, then these handbooks and guides are the places to go, not reference manuals.

Re: Simplified and community-driven man pages

#55

Post by microcolonel »

jmfayard wrote: post #50
pletnes wrote: post #41

Earlier quoted context omitted.

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

For what it's worth, find is truly awful, and tar is just a bit unconventional in terms of option parsing. These are stand-out failures of interface design, for which no documentation would be sufficient for all but the most regular of users.

Re: Simplified and community-driven man pages

#56

Post by onetruepretzel »

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] - https://en.wikipedia.org/wiki/Man_page#Layout

Re: Simplified and community-driven man pages

#58

Post by unixhero »

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 agree. An an author of several command line tools I would never document it's usage in the way the classical man pages are structured. They are in times of dire need, frankly, unhelpful.

I ALWAYS have to Google it, since the man page gave me nothing.

Re: Simplified and community-driven man pages

#59

Post by JdeBP »

pjmlp wrote: post #51
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.

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, Illumos, FreeBSD, and OpenBSD manual pages for the ls command:

* http://nixdoc.net/man-pages/HP-UX/man1/lsf.1.html

* https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.i...

* https://docs.oracle.com/cd/E23824_01/html/821-1461/ls-1.html

* https://illumos.org/man/1/ls

* https://www.freebsd.org/cgi/man.cgi?query=ls

* http://man.openbsd.org/ls

And here is the GNU one from Debian Linux written (it says) by Richard Stallman:

* https://manpages.debian.org/stretch/coreutils/ls.1.en.html

As can be seen, the commercial manual pages are not worse, and are indeed in several aspects better than the GNU one. The same is pretty much true of the non-GNU free operating systems (FreeBSD, OpenBSD, and Illumos) as well.

Notice that ...

* ... only the HP-UX, AIX, Solaris, Illumos, and OpenBSD manual pages have examples (quite apposite considering the headline for this discussion)

* ... only the HP-UX, AIX, Solaris, and Illumos manual pages explain that output falls into three basic forms

* ... only the Solaris, Illumos, and FreeBSD manual pages actually explain in detail the configuration of the colour scheme (HP-UX, AIX, and OpenBSD not having a colour scheme mechanism, in fairness)

* ... only the HP-UX, AIX, Solaris, Illumos, OpenBSD, and FreeBSD manual pages explain what the characters output by the -F option actually signify

* ... only the HP-UX, AIX, Solaris, Illumos, and FreeBSD manual pages explain that the time format used in -l changes according to how long ago the timestamp was (an odd removal for OpenBSD, considering that OpenBSD ls does the same thing)

... and so on.

Re: Simplified and community-driven man pages

#60

Post by rene_bg »

jmfayard wrote: post #50
pletnes wrote: post #41

Earlier quoted context omitted.

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

Thanks for the link to Kapeli/Dash - looks like something that could really make everyday work easier!
Post reply on HN