[da39a3ee]

I’d like to love man pages but

- 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.

[RTFM_PLEASE]

OpenBSD pages (https://man.openbsd.org/) absolutely rock and other, proper BSDs do quite well.

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.

[da39a3ee]

You seem to be missing my point which is that, as a maintainer of a command line tool, I need to and want to cater to users of all OSs. And in fact, I will allocate my efforts more towards popular OSs. I genuinely am sure that your BSDs are a nice environment, but surely you understand how fringe they are? The majority of my users are MacOS+Windows, with substantial Linux also.

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

[Shared404]

> - I feel that they are linux only.

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.

[the_only_law]

FreeBSD has pretty good documentation.

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)

[josephcsible]

> On my MacOS system I can’t rely on man x being the man page for the right version of x.

But isn't that an issue with macOS, not an issue with man pages?

[da39a3ee]

Yes, it is. But MacOS (and Windows) are popular OSs for laptop users. I'm the maintainer of a command line tool that is reasonably popular and I believe that the majority of my users are MacOS. So the question is quite concrete for me -- should I provide documentation in the form of a man page? I do not currently, for the reasons I gave above (although I made a mistake in saying Linux when I meant Linux and *BSD for which I deserve what I get!) But I'd appreciate it being pointed out if my thinking is wrong here.

[enriquto]

> should I provide documentation in the form of a man page?

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.

[da39a3ee]

It would be cool if help2man worked perfectly. In fact the output needs a few fixups -- it looks like it has problems with non-ASCII characters?

But if those fixups can be made automatically it's not bad and I agree might be worth adding to the build.

[enriquto]

Yes, the output of help2man is not perfect. My main gripe is that it imposes a rather strict format for the manpage, and not all manpage markup is available. But it is better than not having a manpage at all.

The problem with non-ascii characters can be solved, though. Just add an option like "-L en_US.UTF-8" to the help2man call.

[da39a3ee]

Thanks. However, now help2man is outputting the unicode character correctly, but `man $help2manOutput` is displaying things like `a(R)` and `a` instead of the unicode character. I've also tried with the `LOCALE=en_US.UTF-8` env var set.