Hacker News Reader

Comment by noja | Hacker News Reader

GNU Parallel - an amazing tool with the most user unfriendly brick-wall-in-your-face documentation imaginable. Shame really - it's great.

View on HN

To be honest the same can be told about many GNU tools. At least myself I still experience this moment of being totally lost infront of the man screen from time to time. Parallel has a nice tutorial https://www.gnu.org/software/parallel/parallel_tutorial.html Have you seen it?

I always get the feeling that most man pages are written for people who already know how to use the commands, rather than people new to them. For example, if I already understand how tar works and have a general idea of how to use it, man tar is great to drill down and find specific options and switches that I need or don't remember, but if I have no idea what tar files are or why would I want them, the man page really doesn't help much in explaining things.

I guess you could argue this is supposed to be so and man pages are doing their job, since they are documentation and not tutorials, but still.

> I always get the feeling that most man pages are written for people who already know how to use the commands, rather than people new to them.

This is actually true. In some of the early Unix documentation or an interview (I can't remember which), one of the core Unix developers said pretty much this, i.e., that man pages were more like a collection of rough notes to help the developers of the Unix system itself not to forget how the commands should be invoked.

Info pages are better for that.

Info pages should be banished from the face of the earth.

https://xkcd.com/912/

I don't get it. The info pages usually have way more information available, and are proper software manuals with plenty of worked out examples, voluminous descriptive text, and hyperlinks to related resources. Try `info sed` and compare that with the bare breakdown of command line options and basic syntax of `man sed`.

I'm not sure what that comic has to do with anything.

Man pages are (in my experience) almost always viewed on a text console or terminal. Info pages work poorly there, and it's just frustrating to be looking for some information in a man page and have to start up some other program with a different UX to complete the task.

Man page standards have places for "See also" and "Examples" and that is good enough.

The options section is no doubt for people, who know the tool. But the huge section with examples is not.

Did you read the "Reader's guide" which is presented before the first option in the man page?

There was a time when many man pages had healthy EXAMPLES section. It seems less frequent now. And info pages are a disaster.

we have bropages for that alas they don't see much activity.

Can I ask to to run these and then comment?

LESS=+/EXAMPLE: man parallel

LESS=+/Reader.s man parallel

man parallel_tutorial

I'm sorry if you got the idea that EXAMPLE section is lacking in parallel manpage.

I wasn't checking that, I was ranting on the general state of man pages. I checked ls, curl, wget, mv - none of which had EXAMPLE sections, and that's where I wrote the comment. Didn't even have parallel on my system.

Gnu man pages almost universally suck. You're expected to use the info docs or their HTMLified versions.

The man page isn't too bad. It is better to just look at examples in my case and see what you can find.

I do agree it needs some work to be a little more approachable.

parallel --help is not friendly, and the man page is too comprehensive - really! - most of it belongs in /usr/share/doc

The examples are a pain to find - jump to the end (here comes the smack in the face) and see pages of differences to other tools.

The page with differences to other tools will be moved to 'man parallel_aternatives' in next version. It made sense when the section was short, but it has grown so big that it can make it harder to navigate.

Thanks for input.

(The trick to find the examples: LESS=+/EXAMPLE: man parallel )

It's a GNU project. It may have a texinfo manual from which the manpage is generated; if so, the info version will have hyperlinks and the like. (But you're probably better off reading the HTML version which should be, as you say, in /usr/share/doc.)

No one looks at texinfo docs.

pinfo is better than info for viewing info pages, but I agree: nobody looks at info pages. It's much easier to google documentation than to navigate to it in info.

I've been using Linux since about 1999 and have never looked at a texinfo page.

Or, at least, I don't think so, because I don't know what they are or how to access them.

At the risk of sounding obnoxious, people might consider writing better documentation - perhaps in a wiki where they can collaborate on it.

I try to convince my teams to use wiki for the first draft and then export to whatever tool you prefer for delivery versions. Sometimes it works, sometimes it doesn't.

A lot of effort has gone into the documentation of GNU Parallel: Intro videos, a one hour tutorial, tons of examples, a man page on the design decisions behind the code, and even a "Reader's guide" in the man-page.

Can you be a bit more specific why you believe it is a "brick-wall-in-your-face"? Did you follow the "Reader's guide", which is before even the first option is introduced?

Should check out the documentation for my Rust implementation of Parallel. Same syntax applies.

https://github.com/mmstick/parallel

> Same syntax applies.

Except that is not entirely true: For instance according to the author the '{= perl expression =}' will probably never be supported.

(Full disclosure: I am the author of GNU Parallel. I fully support building other parallelizing tools, but to avoid user confusion, I would recommend calling them something other than 'parallel' if they are not actually compatible with GNU Parallel).

Reply on news.ycombinator.com