muesliMan pages: technically contain all the information you need, in the same way that a dictionary technically contains every story ever written.
Wolf480plOf course, this is just me being hyperbolic. But I bet you can relate more to it than you'd like.
Both, the format (roff) and the typical man-page content itself feels pretty neglected these days.
I guess legacy and old conventions are holding us back from switching to something that's easier to write, to read/consume, and to maintain. Markdown anyone?
@fribbledom
I haven't written manpages in roff, only in scdoc, but so maybe the tooling is more cumbersome than it needs to be.
But in terms of the way information is organized in manpages? I wholeheartedly disagree. I think it's one of the best documentation formats I've ever read.
@fribbledom
Some of the newer stuff has no manpages, or has weird manpages that don't follow the convention, and that sucks.
I also don't like some of the recent changes to linux manpages, eg. how prctl(2) had all the constants split to separate pages, one per constant.
But if you look at the manpages of Linux syscalls, libc functions, and many non-GNU commandline tools from the pre-docker era, they're usually quite good.
Oh, and section 7 is the best.
@fribbledom
(manpages for GNU sed / awk / grub / etc. suck because they skip details in order to get you to use GNU info)
(manpages for GNU sed / awk / grub / etc. suck because they skip details in order to get you to use GNU info)
Rihards Olups@wolf480pl @fribbledom Yeah, I carefully read the whole bash manpage (once). While it did not contain everything that was useful or important, it was damn good. Same as many other manpages. Disagree with the main claim a lot :)
Jeff@fribbledom @wolf480pl part of me wants to be offended and defensive, but then I realized you are likely a linux user, where gnu has been undermining maintenance of man pages for decades.
They're not neglected on my BSD systems, so, no, I cannot relate. ;-)
Ulises 🌼 ⁂ /I\@fribbledom @wolf480pl When I'm in a hurry, I use TLDR a lot. It often gives you exactly the information you need.
https://github.com/tldr-pages/tldr
https://github.com/tldr-pages/tldr
OblomovAsciiDoc / AsciiDoctor
https://docs.asciidoctor.org/asciidoctor/latest/manpage-backend/
Joe Brockmeier@wolf480pl @fribbledom It is, but that was a funny and sharp way to state the case.
Adriano“Classic Unix documentation is written to be telegraphic but complete… The style assumes an active reader, one who is able to deduce obvious unsaid consequences of what is said, and who has the self-confidence to trust those deductions. Read every word carefully, because you will seldom be told anything twice.”
This is a quote from 20 years ago.
HashRaydamon@adriano @wolf480pl @fribbledom even the 80s Mac OS UI guidelines expected a instinctively curious user
https://blog.prototypr.io/rediscovering-apples-human-interface-guidelines-1987-59731376b39e
@hashraydamon @wolf480pl @fribbledom Having used several Linux flavors for now about 30 years, I would say manpages are, in very very broad terms,
- awful, awful when they are part of the man/info war, especially when they said "go check the info page on this" and the info page wasn't there on the system, not even packaged.
- bad or eh when describing program usage.
- good or very good when describing programming interfaces.
- awful, awful when they are part of the man/info war, especially when they said "go check the info page on this" and the info page wasn't there on the system, not even packaged.
- bad or eh when describing program usage.
- good or very good when describing programming interfaces.
@adriano
Yeah, and that's exactly what I want from reference documentation.
Of course, reference documentation is not a replacement for a high-level overview or for a tutorial. But when you're already familiar with the system, information-dense is what you want.
@fribbledom
Softwarewolf@fribbledom Sometimes the man pages are easy to understand and they contain lots of examples! Sometimes they're very opaque. Depends on the author I guess.
tyzbit
groxx> EXAMPLES
> tool -ahkgdfg 4 ...
>
> SEE ALSO
> bash(1), free(3)
lemgandiLearning to read man(1) pages was crucial to my early career. And maturity as a developer.
Kim@fribbledom This seems like a good time to mention https://tldr.sh/
Eric Bower@fribbledom if only they would contain examples as a common practice
Wolfram Rösler@fribbledom Nonsense