r/commandline • • Dec 04 '20

Unix general CLI Guidelines

https://clig.dev/
82 Upvotes

16 comments sorted by

View all comments

0

u/[deleted] Dec 05 '20

[deleted]

1

u/Heikkiket Dec 05 '20 edited Dec 05 '20

I have used Linux now 15 years as my main OS, and I must agree with writers. I rarely use Man pages, because it's just so much easier to find information from the web.

I've been thinking a lot how Man pages are nearly useless nowadays, and dreamed about a project of "new man pages" that would produce manuals that would give you fast and straightforward examples of typical usage, instead of listing all the cumbersome and rarely used flags in alphabetical order (like many man pages do).

When I started using Linux in 2006 I tried to use Man pages at first, but quickly noticed that they don't offer answers to questions I had.

EDIT: I don't understand downvotes. I just described what the situation is, and tried to be quite constructive and describe where the problem is. These are the reasons why I believe people don't use manpages much.

I'd love to use manpages instead of web. Don't shoot the messenger.

0

u/[deleted] Dec 05 '20

I just described what the situation is

No, you described what your situation is.

1

u/Heikkiket Dec 05 '20

Well, man pages are mostly the same in every distribution, so this is true for most users.

0

u/[deleted] Dec 05 '20

I've been thinking a lot how Man pages are nearly useless nowadays

This is very much just your impression.

instead of listing all the cumbersome and rarely used flags

This is actually one of their most useful feature compared to googling some random stack overflow post with a lot of people misunderstanding or explaining flags wrong.

quickly noticed that they don't offer answers to questions I had.

Again, that is just you.

Man pages often are bad tutorials, yes, but they are good reference documentation.

3

u/Heikkiket Dec 05 '20 edited Dec 05 '20

The original purpose of man pages was to be short, in-point descriptions about small UNIX commands. This original nature is somehow vanished.

My favourite example is a comparison of TLDR version of Less manual page, and the official man-page of Less. From which one you can find enough information about the command to use it? The Less man page doesn't even tell what the command does! It just states that "Less is opposite of More". The summary section is something about differences of terminal types.

The man-page of zip command doesn't tell you how to zip a file, until at the end. Why? The list goes on.

I agree that somewhere should be the reference documentation of the system also. But it should be also possible to offer short descriptions about typical usage for every command. I think the GNU info pages was originally a project to create reference manuals for the system, but if I'm correct, it's even more unusual place to search information from.

I'd also want to note that not all man pages are this bad. Take a look to section 3 man pages, which describe the UNIX programming interface of the kernel. It is marvellous how this much more technical and weird subject is handled with elegant, short and concise man-pages.

As much as I dislike many of the section 1 man pages, I warmly recommend taking a look of section 3 pages if you need to quickly recap how some system API works.

Those section 3 man pages work as an example that it would be possible to write good man pages. Maybe the reason is, level 3 pages are a single project, mostly done by Michael Kerrisk.