search

click-contrib / click-man

Automate generation of man pages for python click applications :star:
MIT License
163 stars 35 forks source link

Generating portable manpages #11

Open richardipsum opened 6 years ago

richardipsum commented 6 years ago

Hi,

I've seen that click-man appears to generate man pages with blank lines, which I'm given to understand are non-portable, by which I simply mean that some versions of troff will not always do the "right" thing in the presence of blank lines.

On submitting a patch to the project concerned I was told that the man pages are automatically generated by click-man.

Do you agree that my patch to the above project is correct? If so would you accept patches to make the output of click-man match the modified man pages in the above patch?

Thanks, Richard

timofurrer commented 6 years ago

Okay, wasn't aware of that. I'm happy to review PRs :tada:

richardipsum commented 6 years ago

@timofurrer Thanks for such a quick response, I will attempt a PR as soon as I can.

richardipsum commented 6 years ago

@timofurrer I've opened https://github.com/click-contrib/click-man/pull/13 which solves one of the issues raised by this ticket.

richardipsum commented 6 years ago

@timofurrer Thanks for merging #13 so quickly!

I have other thoughts on how to handle whitespace (indentation) issues. It's simple enough to replace the 2 space indentation generated for commands by click-man with .RS and .RE. And I'd be happy to submit a PR to fix that.

Slightly trickier is whether clickman tries to convert indents in the source code to .RS and .RE. It could be attempted but wouldn't be fool proof since we'd have to assume what constitutes an indent level (i.e. 4 spaces). Is a PR for this something you'd be interested in or would it complicate the tool too much? I also think that if this were added it would perhaps also require additional user options to allow the user to specify the indent type i.e. indent-char=SPACE indent-width=4 or something like this to allow them to override the 4 space default. :tropical_fish:

richardipsum commented 6 years ago

@timofurrer Hey, I figure you may have missed this, or you may just be busy, either way this is just a reminder that I'd be curious to know if you have any thoughts on the above. :cat:

richardipsum commented 6 years ago

@timofurrer I don't know whether lack of a response here means I should attempt a PR or close this issue?

timofurrer commented 6 years ago

@richardipsum the lack of response is due to the lack of time I currently have - I'm sorry for that.

It's simple enough to replace the 2 space indentation generated for commands by click-man with .RS and .RE. And I'd be happy to submit a PR to fix that.

Sounds good :+1: Go for it!

Slightly trickier is whether clickman tries to convert indents in the source code to .RS and .RE. It could be attempted but wouldn't be fool proof since we'd have to assume what constitutes an indent level (i.e. 4 spaces). Is a PR for this something you'd be interested in or would it complicate the tool too much? I also think that if this were added it would perhaps also require additional user options to allow the user to specify the indent type i.e. indent-char=SPACE indent-width=4 or something like this to allow them to override the 4 space default. :tropical_fish:

I certainly see the problem. However, I'm struggling why you would want source code in the man page of a CLI tool. Maybe we should just strip source code from the man pages? If we go for the indent in source code as well, we definitely have to allow the user to specify the level.

richardipsum commented 6 years ago

@richardipsum the lack of response is due to the lack of time I currently have - I'm sorry for that.

No worries, thanks for getting back to me.

It's simple enough to replace the 2 space indentation generated for commands by click-man with .RS and .RE. And I'd be happy to submit a PR to fix that.

Sounds good :+1: Go for it!

Cool, I'll prepare a PR

I certainly see the problem. However, I'm struggling why you would want source code in the man page of a CLI tool. Maybe we should just strip source code from the man pages? If we go for the indent in source code as well, we definitely have to allow the user to specify the level.

Sorry I mean the comments in the source, which get used in man pages, should the tool attempt to convert any indentation in a comment into .RS .RE sequences?