-
-
Notifications
You must be signed in to change notification settings - Fork 7
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Added man page support to print-documentation #23
Conversation
Hey @halcyonseeker , Great PR, thanks! Please find some feedback in the comments below.
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.
Absolutely! Having multiple slots for each would probably be too much, but a single option (e.g. This slot would be similar to what Let me know what do you think, thanks! |
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 😅) |
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! :) |
Merged, thanks! |
I added a specialization of
command
'sprint-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 thecommand-usage
slot, which, in the example programs, also contains flags. This results in SYNOPSIS lines containing redundant information like this one for intro: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 tocommand
specifically to generate these?