Add sources for man pages in a convenient format

[MestreLion]

As command-line options for the tools grow and change, specially in restore-mtime, the man pages inevitably get outdated. Also, man pages (could) contain information and knowledge that do not really belong in a tool's --help but should be more visible than a source code comment, TODO or FIXME. For example, info about #38 could be added in a "Known Bugs" or "Limitations" section.

But editing man pages by hand is very difficult for those unfamiliar with nroff syntax (or is it groff? roff maybe?), myself included. It would be great if the project had such man pages in a format that's more easily editable, then converted to nroff using a tool in a build script.

Ideally such tool would also invoke the tool's --help to keep the man pages updated with current options. Preferably not enforcing a direct copy-and-paste but allowing a more detailed, expanded description on each option, while deleting obsolete and warning on any missing ones.

For those familiar with such workflow (@kilobyte , @dwfreed ?), what are the current/suggested standards? Markdown, AsciiDoc, something else? Any suggestions on how I should implement this in this project? @gebailey , as the author of current man pages, how did you create them? By hand? Did you use any tools to generate them from a template/--help or to automate the process in any way?

I'm completely unfamiliar with this whole thing, so any directions are much appreciated!

[kilobyte]

We use Markdown at work, and I've dealt with AsciiDoc manpages too — they are indeed easy to edit, but converters often fail to do what you want, with no apparent way to override.

Back in the days, I had good experiences with POD, but that's a thing for Perl-heads.

I for one tend to just deal with troff directly, this way there's no converters to deal with. But if you need a more readable format, that'd be Markdown as the others are quite obscure.

[MestreLion]

@kilobyte , thanks for the input! If using Markdown, what would be the toolchain and steps to convert it to *roff? And how to generate it from (and keep synced with) a --help?

Also, should I keep the converted, final *roff man pages in the repository, like now? Or should I consider they're "built artifacts" and keep the markdown sources only? Is there any convention / preferable way for packages?

[kilobyte]

At work we're using pandoc, but I have serious doubts that's a recommended tool. Alas, I'm afraid you'd need to research this more.

As for build artifacts, as a packager my preference is definitely to not include them. Dunno what's better for ordinary users.

[MestreLion]

I suspect ordinary users never touch the *roff files. I'm not sure if it's possible to use them from a local git clone, or if there's a way to install them in $HOME in a way man could pick them up. So I've always considered them a (very welcome) addition meant for packagers only. So if you guys prefer to build the manpages when creating the .deb/.rpm packages instead of using the pre-made roffs, I can substitute them for the sources+toolchain as soon as I... well, as soon as I know what the sources and toolchain will be :)

Is there any dh- helper for man pages? Does it require (or suggest) any source format? Can it handle Markdown?

I'm currently researching about AsciiDoc's a2x tool, seems to be what I'm looking for. Not sure how trivial/conventional is to include such step in a source package build.

[MestreLion]

I suspect ordinary users never touch the *roff files. I'm not sure if it's possible to use them from a local git clone, or if there's a way to install them in $HOME in a way man could pick them up.

Note to self: there is! Just copy them to, not surprisingly, ~/.local/share/man/man1 (or, even better, ${XDG_DATA_HOME:-$HOME/.local/share}/man/man1) and man will happily find them!

[MestreLion]

Another note to self: add the above to the README "manual install" instructions (pun intended)