BCHS: OpenBSD, C, httpd and SQLite web stack

Re:BCHS: OpenBSD, C, httpd and SQLite web stack by da39a3ee on Wednesday January 19, 2022 @08:07AM (#29993101)

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.

[ Parent | on HN ]

Re:BCHS: OpenBSD, C, httpd and SQLite web stack by enriquto on Wednesday January 19, 2022 @09:59AM (#29994393)

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

[ Parent | on HN ]

Re:BCHS: OpenBSD, C, httpd and SQLite web stack by da39a3ee on Wednesday January 19, 2022 @12:02PM (#29996351)

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.

[ Parent | on HN ]

Re:BCHS: OpenBSD, C, httpd and SQLite web stack by enriquto on Wednesday January 19, 2022 @12:19PM (#29996598)

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.

[ Parent | on HN ]

Re:BCHS: OpenBSD, C, httpd and SQLite web stack by da39a3ee on Wednesday January 19, 2022 @01:01PM (#29997398)

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.

[ Parent | on HN ]

Re:BCHS: OpenBSD, C, httpd and SQLite web stack by enriquto on Wednesday January 19, 2022 @01:21PM (#29997733)

This sounds like a problem with your pager, that is used to scroll the output of man pages in the terminal. Do accents appear correctly on other manpages in your system? If I recall correctly, on macos catalina I had to set my locale variable LC_CTYPE (and not LOCALE) so that the less pager recognized the accents.

[ Parent | on HN ]

Re:BCHS: OpenBSD, C, httpd and SQLite web stack by da39a3ee on Wednesday January 19, 2022 @01:51PM (#29998235)

I don't think it's a pager problem for the following reasons:

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

[ Parent | on HN ]

Re:BCHS: OpenBSD, C, httpd and SQLite web stack by enriquto on Wednesday January 19, 2022 @02:15PM (#29998570)

This is not the most appropriate place for this sort of fine-grained debugging. I'd suggest to try your generated manpage on another computer to see if it displays correctly. The only thing that I can say is that "it works for me" but of course this answer is not useful :)

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!

[ Parent | on HN ]