Also, man pages are for more than just system utilities (man(1)). Which binary should hold pledge(2) (https://man.openbsd.org/pledge), exactly?
Your man pages should be updated when the associated tool is updated.
You are describing a MacOS issue, with its terrible package management, and frustrating toolchains.
In fact MacOS has an excellent package manager -- it's called homebrew. I don't really want to argue about it but you're the one who made an unjustified assertion about an OS which I bet you don't use. People like you insist that it's bad but no-one who uses it knows why. I maintained my own Linux laptop for 10 years, and for the last 10 years I've used homebrew on a Mac. It has literally never given me any problems! I've never even searched the issues on Github for a problem as far as I can remember.
Honestly I think that the thought processes of most Linux/Unix enthusiasts like you who criticize homebrew are
1. We hate MacOS because childish anti-capitalist ideologies
2. Therefore we will not admit that a nice command-line development environment can be created on MacOS
3. Therefore homebrew is bad
They're actually better on Free/Open BSD in my experience. As stupid as it makes me sound, I often struggle to parse Linux man pages, but the BSD's I've had no trouble with for a variety of topics.
> - I feel that a small amount of plain text documentation should be stored in the executable,
Isn't this how --help usually works? I would also rather have more documentation embedded, at least for some executables.
Comparatively, I’ve found NetBSD documentation to be lacking, although NetBSD seems to take the cake on code quality and legacy architectures (a feature I find my delve right now.
On the wider discussion of doc, I’ve found Linux kernel documentation to be a pain in the ass, and sometimes ever worse than windows kernel documentation (which I won’t even both to get into)
But isn't that an issue with macOS, not an issue with man pages?
Yes, and this may be a much smaller effort than you suspect. Only by writing the output of --help in a certain order, you can use the "help2man" tool to generate a beautiful manpage automatically. Notice that your users do not need to have help2man installed, you run it yourself as part of your build process, to create the manpage from the latest source code.
It is very likely that if your tool already has a --help option, you don't really need to do anything to have a manpage. Just call help2man from your makefile.
But if those fixups can be made automatically it's not bad and I agree might be worth adding to the build.
The problem with non-ascii characters can be solved, though. Just add an option like "-L en_US.UTF-8" to the help2man call.
- If I do `man help2manOutput | cat` then it does not page, but I still see `a` and `a(R)` in place of the desired unicode characters
- `less help2manOutput` renders them correctly
- In general I have no problem viewing unicode characters in less: I'm familiar with env vars such as LESS and PAGER.
The main site of development for help2man seems to be this:
https://salsa.debian.org/bod/help2man
I'm sure they'll accept pull requests that fix problems. Happy hacking!
- I feel that they are linux only. On my MacOS system I can’t rely on man x being the man page for the right version of x. I know that in principle there are environment variables that make sure i’m getting the gnu core utils version or the base homebrew version rather than the system BSD version, but it’s too many moving parts. Furthermore even if I get it right, I can’t expect people I’m working with or mentoring to get it right, hence I can’t recommend man to them for documentation. God knows about man pages on Windows.
- I feel that a small amount of plain text documentation should be stored in the executable, not separately. Isn’t it a holdover from the vastly more constrained computing environments of the 70s and 80s that we’re keeping man pages separate from the executable? Its just asking to get out of sync / incorrectly paired up.