Generating portable manpages

[richardipsum]

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]

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

[richardipsum]

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

[richardipsum]

@timofurrer I've opened #13 which solves one of the issues raised by this ticket.

[richardipsum]

@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. 🐠

[richardipsum]

@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. 🐱

[richardipsum]

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

[timofurrer]

@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 👍 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. 🐠

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]

@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 👍 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?