Added man page support to print-documentation

[halcyonseeker]

I added a specialization of command's print-documentation method which produces documentation in the mdoc format for man pages. It seems to work well for the programs in the examples directory, as well as Leibowitz, a subcommand-heavy program I've been developing. For reference, the man page generated by this method is attached here.

This new method works pretty well so far, but there are two limitations I'm not sure how to resolve:

Firstly

Mdoc is designed to represent parts of a man page semantically, with command-line flags and arguments in the SYNOPSIS section typeset with the .Op macro. This is fine for flags, but clingon doesn't seem to expose a way to find the free arguments a command makes usage of. The closest I found was the command-usage slot, which, in the example programs, also contains flags. This results in SYNOPSIS lines containing redundant information like this one for intro:

SYNOPSIS
       clingon‐intro [-‐version] [-‐help] [-v, -‐verbose] [-u, -‐user VALUE] [[‐v] [‐u <USER>]]
       clingon‐intro shout [-‐version] [-‐help] [[options] [arguments ...]]

In Leibowitz I resolved this by not writing the flags in the command-usage slot, but judging from clingon's examples and documentation this doesn't seem to be the way it's intended to be used.

What do you think would be the best approach here?

Secondly

Man pages conventionally have quite a few sections (the previously linked mdoc(7) also lists context, implementation notes, return values, files, exit status, diagnostics, errors, see also, standards, history, caveats, bugs, and security considerations) which don't correspond directly to slots of the command class. Some of these are really important, do you think it would make sense to add slots to command specifically to generate these?

[dnaeon]

Hey @halcyonseeker ,

Great PR, thanks!

Please find some feedback in the comments below.

In Leibowitz I resolved this by not writing the flags in the command-usage slot, but judging from clingon's examples and documentation this doesn't seem to be the way it's intended to be used.

If you are looking for something along the lines of position arguments like in #19 , then this is not supported at the moment.

If you want to customize the usage information for a command, currently it is done like you've implemented here.

Man pages conventionally have quite a few sections (the previously linked mdoc(7) also lists context, implementation notes, return values, files, exit status, diagnostics, errors, see also, standards, history, caveats, bugs, and security considerations) which don't correspond directly to slots of the command class. Some of these are really important, do you think it would make sense to add slots to command specifically to generate these?

Absolutely!

Having multiple slots for each would probably be too much, but a single option (e.g. COMMAND-EXTRA, COMMAND-EXTRA-DOC, or similar) which is a list of cons cells to represent each section and it's documentation might be the way to go.

This slot would be similar to what COMMAND-EXAMPLES does, which allows specifying multiple examples.

Let me know what do you think, thanks!

[halcyonseeker]

If you are looking for something along the lines of position arguments like in https://github.com/dnaeon/clingon/issues/19 , then this is not supported at the moment.

That is what I was thinking of, makes sense.

What you described of an extra documentation slot makes a lot of sense, do you think it would be best for me to add those changes to this PR or open a new one? (I'm not too familiar with the Github PR workflow 😅)

[dnaeon]

What you described of an extra documentation slot makes a lot of sense, do you think it would be best for me to add those changes to this PR or open a new one? (I'm not too familiar with the Github PR workflow 😅)

Let's use a separate PR for the new extra documentation slot, as it's a separate feature.

I've added one comment to the code about a special var, please check it out.

Thanks again! :)

[dnaeon]

Merged, thanks!