search

jyn514 / saltwater

A C compiler written in Rust, with a focus on good error messages.
BSD 3-Clause "New" or "Revised" License
294 stars 27 forks source link

Generate man pages using help2man #504

Open jyn514 opened 4 years ago

jyn514 commented 4 years ago

I don't plan to learn troff, so this seems like a low-maintenance way to still have man pages.

https://www.gnu.org/software/help2man/

jyn514 commented 4 years ago

Originally suggested by @chorman0773 (thank you!)

jyn514 commented 4 years ago

For this to work we should also change usage: saltwater ... to usage: swcc (should be fixed anyway).

jyn514 commented 4 years ago

In an ideal world this would be autogenerated and committed to the repo every time HELP or USAGE is changed, and enforced in CI somehow, with instructions for how to autogenerate it if there's a difference.

chorman0773 commented 4 years ago

I should probably mention this, now before I forget again. I took a look at the program, and there are some modifications necessary to HELP, in order to be usable for help2man. In particular:

  1. I don't know that help2man allows anything before the Usage: line, I have not yet tried.
  2. As previously mentioned, the Usage: line should use the program name in argv[0], not a hardcoded value. This is probably the hardest part.
  3. There should be at least a line of description belong the last usage line, you can also put any additional information here. (there needs to be a blank line between the description and Options: in order for it to understand the header).
  4. AFAIK, Flags: and Options: need to be merged, and Args: removed. You'd mention what the input files are about in the description. Options: is the OPTIONS header in the man page. I don't believe there are any other special headers parsed like this (though the part that starts with Copyright (C), usually in the --version, is parsed to the COPYRIGHT header).

For the actual help2man call, you can look at the exhaustive options from its own man page (man 1 help2man), but the ones I use are --name="short description" and --section=<section> (section usually being and defaulting to 1, however, I automate the use, so using the option explicitly means I can change it to --section=8 for the things that need to be in section 8).

I can resolve most of these (though I'd need a good description to put into that part of the command for that 3). I'm unsure of how to resolve (2) without moving the help into the format string, which requires hardcoding it there (one of the few problems with compile-time resolved format strings).