Perlpod, pod2man: get ascii grave accent in ROFF \(ga.

[Erwin Waterlander]

Hi,

I'm in the process of converting a manual written man page in ROFF
format to POD.

In ROFF I use these commands:
\(ga grave accent
\(aq apostrophe quote

These ROFF commands will produce an ASCII grave accent (ASCII 0x60) and
apostrophe quote (ASCII 0x27) in the man page in any locale environment:
ASCII, Latin1 or UTF-8.

If I use in ROFF plain ` and ' I may get other characters displayed in
man depending on the locale character encoding setting of my
environment. In an UTF-8 environment I will get unicode equivalents.

Suppose I want to do the same in POD, produce ASCII grave accent
regardless of the locale, how do I do that? (don't ask why). Or in other
words: what is a neat way to produce \(ga and \(aq in ROFF from a POD file?

regards,

Erwin

 

[Erwin Waterlander]

Op 7-10-2009 19:34, Ben Morrow schreef:

You can't, in general, without using a custom POD formatter that does
what you need.

Ben

I was afraid of that. This leaves nothing else then some 'sed' post
processing.

With a plain ` and ' in ROFF I see for instance this happening on RedHat
Enterprise Linux 4: In an ASCII locale both ` and ' are converted to the
apostrophe quote (0x27). `quote' becomes 'quote'. That's wrong. In a
Latin1 locale both quotes are converted to a Latin1 quote (0xB4) (wrong
again). On RHEL3 these problems don't occur (strange?). Anyway, if I use
\(ga and \(aq in ROFF the quotes are always displayed correctly on any
system.

Erwin

 

[Erwin Waterlander]

Op 10/07/2009 10:32 PM, Ben Morrow schreef:

'Wrong' according to whom? Pod is not supposed to be a highly-specific
document creation system, it is supposed to be a quick and easy way of
documenting Perl with lots of DWIM in the formatters.

I know you said 'don't ask', but I have to ask why you think you need
this. It sounds like you may be better served by some other markup
language.

It is not indented for normal text but for unix shell script examples.
There a backqoute replaced by a qoute results in a wrong script.

In normal text there is no issue. I don't care that quotes in normal
text are translated to the current locale.

One more thought: have you tried using E<96> and E<39>?

That would not help.

 

[Erwin Waterlander]

Op 10/08/2009 03:00 PM, Ben Morrow schreef:

Have you indented your examples, to make them into a 'verbatim
paragraph'? If you have, the pod formatters should be leaving backquote
alone (after all, it's just as special a character in Perl as in shell).
If they are not, you have a buggy version of whatever pod tool you are
using; upgrade to the latest version, and report a bug if it's still
there.

Ben

This is the solution (also thanks to Jari Aalto):

POD:
code=`cmd` # example

pod2man produces this ROFF:
\& code=\`cmd\` # example


An escaped backquote in ROFF, has the same output as \(ga.

man 7 groff:
\` The grave accent `; same as \(ga. Unescaped: left quote,
backquote (ASCII 0x60).


So now everybody who uses the man page will see an ASCII backquote.

regards,

Erwin

 

[Erwin Waterlander]

Op 10/08/2009 04:50 PM, Erwin Waterlander schreef:

Op 10/08/2009 03:00 PM, Ben Morrow schreef:

This is the solution (also thanks to Jari Aalto):

POD:
code=`cmd` # example

pod2man produces this ROFF:
\& code=\`cmd\` # example


An escaped backquote in ROFF, has the same output as \(ga.

man 7 groff:
\` The grave accent `; same as \(ga. Unescaped: left quote,
backquote (ASCII 0x60).


So now everybody who uses the man page will see an ASCII backquote.

regards,

Erwin

Actually the problem was that I used a too old version of pod2man. The
version shipped with RHEL4 is 1.10 (2002/07/16). This version produces
un-escaped backquotes in ROFF. A more recent version (1.16 2006)
produces correct ROFF.

Erwin