search

alavrik / piqi

Piqi – universal schema language: JSON, XML, Protocol Buffers data validation and conversion
http://piqi.org
Apache License 2.0
246 stars 36 forks source link

Properly escape hyphens to minuses in command line options #45

Closed maurer closed 10 years ago

maurer commented 10 years ago

groff interprets "-" as a hyphen in unicode, as distinguished from a minus. As a result, flags in the man page could not be previously copied and pasted into a terminal. This patch properly escapes them to make them minuses, and thus work properly.

alavrik commented 10 years ago

Thank you for the patch and apologies for the delay. In fact, piqi.1 is generated automatically from tools.md using pandoc -- see doc/Makefile. I include the latest piqi.1 in the repo so that packaging scripts don't have to depend on pandoc.

Would it be possible to automate this transformation? Otherwise, it won't be possible to consistently apply to future version of auto-generated piqi.1.

maurer commented 10 years ago

I'll look into this again at some point, but on a cursory review, I can only seem to get pandoc to escape all hyphens or none of them, neither of which is correct.

alavrik commented 10 years ago

@maurer just though about this. What would be a disadvantage of replacing all dashes/hyphens to minuses by running pandoc output through sed -e 's/-/\\-/g'? There should be little difference when it comes to visual rendering and it solves the original problem. What do you think?

maurer commented 10 years ago

That will make the command lines copypasteable, which is the biggest issue. It will cause the rendering to be slightly less pretty on UTF-8 supporting terminals, but that seems a reasonable tradeoff.

alavrik commented 10 years ago

Added the escaping as we discussed. I guess we can close it now?

By the way, I noticed you've submitted piqi for inclusion in Debian. I am not familiar with the process but I'd be happy to make necessary changes in the upstream to make packaging easier. Can you email me at alavrik@piqi.org so that we could coordinate what needs to be done? Thank you.