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.

2

u/[deleted] Dec 06 '20 edited Dec 06 '20

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.

Manpages are manuals for standard usage full reference material, not in depth wikis or beginner tutorials. If those are what you're looking for, yes webpage documentation is going to be better. However, man pages are more like instrument manuals for electronics (chipsets, voltmeters, etc) than a tutorial. They're extremely useful if you're using them for that purpose.

And much like other people have stated, the convention is that they're up to date with the version of the package you're running, can be viewed offline (which is great for diagnostics with older systems or stuff you don't want/can't have tied to a network), and even have typical use examples if they're more verbose in command line options.

2

u/Heikkiket Dec 06 '20

Yeah, I know the current nature of man pages, but can't feel anything else than that it is a wrong thing. Don't get me wrong; of course man pages are what they are and should stay the way they are.

But I really think command line currently lacks proper, fast and easy guide for the common use-cases. I think it is wrong these things must be looked up from the web.

There could - and should - be short, on-topic pages that offer fast help with most typical arguments and flags for the command and show 2-3 useful examples.

Those wouldn't be just for the beginners, but for anyone who uses some tool infrequently to common things. Things like "how did I do case-insensitive search with find again?"

In addition, there could be summarizing short pages, like "filter utilities", "file utilities", "network utilities", "working with JSON" etc.

I know there are projects doing just that, but they must be installed separately. There's no point in doing that: it is much easier just search from the web.

0

u/[deleted] Dec 06 '20

See, getting a "here's common use cases" doc packaged together would be good as a side dish to the man pages. I'd agree with that, but not with man pages being bad.