4 ms·
man(1) pages on linux are almost all terrible. Unworthy of inclusion in any manual. Proper manuals have examples of use. Many linux man pages don't even discu
by tuatoru 4y ago
man(1) pages on linux are almost all terrible. Unworthy of inclusion in any manual. Proper manuals have examples of use. Many linux man pages don't even discuss (or list, even!) return codes or failure modes.
- packetlost 4y agoYeah, I really don't understand the aversion to examples. The sorta-standard format for man pages is... extremely confusing, even after a decade of using them.
- spacemadness 4y ago“you should be smart enough to figure this out from here” bravado probably for some cases.
- soraminazuki 4y agoYou do realize that writing good docs takes time, skill, and effort, right? Not to mention the docs you're blanketly scorning at were most likely written on someone's spare time who has no obligation to do so.
- deleted 4y ago[deleted]
- packetlost 4y agoWhen you have some people not doing it, that's fine, they own their time. When you have have almost no one doing it, that's a cultural issue. I'm saying Linux/Unix man pages have inherent and probably very old cultural issues leading to a lack of baked-in examples.
- masfuerte 4y agoGnu stuff tends to be properly documented in info, not man. But yeah, loads of stuff just isn't well documented.
- floren 4y agoStallman's sad devotion to that ancient religion... ITS has been effectively dead for how many decades now, but by god we're gonna force everybody to use a port of their online documentation system if we can! At least we're past the bad old days when you'd open a man page and it would just be a stub saying "look at the info docs, IDIOT"
- pxc 4y agoSome of the manpages for utillinux (e.g., chsh, useradd) are pretty barebones and don't include examples, but off the top of my head I can't think of a major GNU utility that doesn't have EXAMPLES sections in its manpages. GNU coreutils, find, sed, and grep all have such a section in their manuals. What are you thinking of that is example-less?
- stametseater 4y agoGNU ls's manpage has no examples, but it's also a thousand words long so it hardly seems fair to characterize it as bare-bones. All in all, I find that manpages on Linux are usually pretty good, particularly compared to systems like MacOS where many daemons and utilities seem to have no manpage at all. People are far too quick to slag manpages, which probably has something to do with the `man` utility itself being a bit archaic. Common Linux desktops could probably do a better job of advertising GUI-based manpage readers like khelpcenter.
- pxc 4y agoI'd like slightly fancier system (no, not info), but being able to look things up without leaving the terminal is so underrated imo. It makes looking things up a lot faster.
- Arnavion 4y agoPOSIX ls's manpage has examples. Well, one example, of `-laRF`. But also I can't imagine what good more examples will do anyway. `-lahR` cover the vast majority of common uses.
- stametseater 4y ago> -lahR` cover the vast majority of common uses. For me, 99% of the time I use -ltrh and -ltrha. But instead of -R, I use other utilities like fzf, find, or tree. Tree is really nice for a quick overview of directory structures.
- wallfacer120 4y ago[dead]
- brwck 4y ago> Proper manuals have examples of use This is what microsoft did well with powershell's help system. They have examples. Tons of them. Why man pages do not is beyond me when most of the time, an example or two is all we need. I bet most people go to the man pages and then google for examples because the man pages weren't helpful.