51–60 of 179 posts
A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.
How is this "rapidly decaying third-party documentation" in any way that man isn't?
A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.
It seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.
The focus has been making it easier for the developers to write literally anything. One thing uses sphynx another uses man another uses doxygen or what the hell ever. Users aren't developers. This is why everyone ends up on google and ends up on stackoverflow or random blog or watching youtube.
The barrier to entry is much lower with some simple markdown thing. Hell, I was thinking about how to abuse this thing to make my own notes about commands.
Shout out to http://cht.sh , which could be used without installing anything: curl cht.sh/tr
e.g. http://cht.sh/tar
Earlier quoted context omitted.
It may contain all information, but a clear F on UX. What I find annoying is the number of command line programs that don't even have man pages anymore. Or maybe that's just an artifact of installing them with brew? What I find interesting is that for the most part (there are exceptions), the older the man page, the more useful it is. Realistic examples. Succinct descriptions. User-friendly terminology. Too many of t…
I have added packages to Homebrew, and they install man pages when available. Homebrew provides a pretty simple mechanism for doing so. The problem is that many projects just prefer web documents to man pages, likely because the man page tooling is not great.
Earlier quoted context omitted.
I've not used man enough to know the how to look up a particular section. This is a good opportunity for me to compare the out-of-the-box results from tldr vs man: https://tldr.ostera.io/man https://linux.die.net/man/1/man "Why not just install these as man pages in their own section and read them with man?" Because downloading the default program is much easier, most users aren't that concerned about adding a small…
I don't think tldr is a small CLI program unless you already have Node.js installed. :) And I also don't see why installing that is easier than installing man pages, if appropriately packaged. (I'm not claiming they are currently appropriately packaged, I'm just saying that's what they could have done instead of writing a client.)
I just found that and installed it after reading this thread. It looks like on first run, like "tldr tar", it calls "git clone" on some repo. Thereafter, other incantations like "tldr grep" use the already local repo. And the repo can be updated with tldr --update. Seems very fast.
A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.
It seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.
Earlier quoted context omitted.
It seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.
The maintainer of the manpages project, Michael Kerrisk, is quite responsive and interested in improvements. I've generally found the maintainers of other software to be receptive to documentation patches, as well.
Earlier quoted context omitted.
It seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.
Do you have examples of that refusal? I'm unfamiliar.
While some man pages have examples, I don't know if man page writers see their job as teaching readers how to use a utility. The goal of man pages more often seems to be _reminding_ a person already familiar with the tool how to use a tool.
I'm, umm, _reminded_ of project READMEs. I've come to assume that when I go to a project on GitHub, I'm going to get everything I need (or pointers to everything I need) to get started with a project, but often there's a project web site that is intended to serve that purpose. I just ran into this yesterday with Falcor.
Not all man pages are like this obviously. Specifically, the section three man pages on C functions do a good job fully documenting functions.
Earlier quoted context omitted.
It seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.
Do you have examples of that refusal? I'm unfamiliar.