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

121–130 of 169 posts

Re: Simplified and community-driven man pages

#121

Post by gboudrias »

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.

Good to know, thanks! :)

Re: Simplified and community-driven man pages

#122

Post by vram22 »

jmfayard wrote: post #77
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…

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…

I agree with your point. There should be easier ways of doing some things in Unix. But since there are not (for some things, anyway, and I say this as a long-time Unix guy), sometimes, scripts can help. Here is one example by me:

m, a Unix shell utility to save cleaned-up man pages as text:

https://jugad2.blogspot.in/2017/03/m-unix-shell-utility-to-s...

This tiny script lets you generate man pages as cleaned-up text, saves them in a ~/man directory, and you can from then on, open them in your favorite text editor or even pager (less/more/pg/etc.) and view them. Created it out of real-life personal need some years ago, on a Unix system, but is still useful on Linux and other Unix-like systems today.

Re: Simplified and community-driven man pages

#123

Post by JdeBP »

detaro wrote: post #66
JdeBP wrote: post #3

Duplicates https://news.ycombinator.com/item?id=15769046

please don't point out empty discussions without upvotes as duplicates, unless there are tons of those recently. Reposts are explicitly allowed on HN under these circumstances.

At the time that I wrote that this was an empty discussion too. You should bear in mind when things are written.

Re: Simplified and community-driven man pages

#124

Post by Spivak »

detaro wrote: post #78
carlosrg wrote: post #74

Earlier quoted context omitted.

"Community-driven" doesn't mean mindlessly accepting every patch that is submitted. Respecting the well-known structure of man pages is a good thing.

Most of the criticism here is exactly about how people do not like the structure of man pages for this use case. If the parent suggests contributing to man pages as a fix for these issues, "Respecting the well-known structure of man pages" goes counter to that goal and suggests that solving this issue outside of man pages actually is the better solution.

It's more important that there is convention than that the convention is optimal.

If the problem is that manuals aren't user friendly enough to new users and should have more examples of common tasks then they belong in the EXAMPLES section.

There's nothing that says you need to stick to the conventional sections either. A TUTORIAL section wouldn't be out of place.

Re: Simplified and community-driven man pages

#125

Post by wodenokoto »

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…

Why should good documentation not be bundled with the product?

Re: Simplified and community-driven man pages

#126

Post by justin66 »

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…

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

That is just a terrible idea. First, if what you're putting in the synopsis is not "a brief summary or general survey of something" then the section is misnamed or the content does not belong there. Examples don't belong there. Second, and more importantly, plenty of commands can do enough damage that people ought to read up on what they do before receiving an example. You're giving someone a false sense of confidence if you throw an example at them first thing. That's appropriate enough in some contexts, but not in official documentation for software tools.

> The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad.

The problems you go on to list have nothing to do with the structure, and everything to do with the content contained within that structure.

> No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial.

Since "documentation experts" write documentation this way, it's hard to imagine why you'd assert this.

Re: Simplified and community-driven man pages

#127

Post by wang_li »

jmfayard wrote: post #77
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…

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…

If your idea of what man is comes from using Linux, then you really haven't had a good exposure to what good documentation can be. Try Solaris or FreeBSD.

Re: Simplified and community-driven man pages

#128

Post by crispinb »

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

> and the examples section is usually last

A far better answer to this would have been a project to (1) improve man page examples, and then (2) create a small alternative man page client that displays only the examples (or puts them up top).

Having said that I do see the need for what tldr is doing, even though I would have preferred it added to existing tools. More often than not I only find man pages useful after I have needed to look up something. They're usually OK for wholistic understanding, but often too dense and assuming of far too much contextual knowledge to be useful in the heat of battle.

Re: Simplified and community-driven man pages

#129

Post by crispinb »

jap wrote: post #40
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

Good idea. I just suggested something very similar before seeing your comment. Now all you need to do is write this up as a shell command ;)

Re: Simplified and community-driven man pages

#130

Post by kleiba »

jmfayard wrote: post #103
kleiba wrote: post #91

Earlier quoted context omitted.

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.

Sure, you're right, it's not the same thing. I just gave a simple example of something that's close, but I'm not even using a bash function like that myself. If I did, though, I guess the 8th occurrence wouldn't be so bad in my book, since the results can be scanned rather quickly.

You could always make your function more clever, e.g.:

    function mano() {
        man "$1" | grep -A1 -- "$2\\b"
    }
or

    function mano() {
        man "$1" | grep -A1 -- "$2  "
    }
but most probably, you will still run into edge cases that won't work properly. For instance, only one of the two versions above still works with "test -e".
Post reply on HN