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

Discussion in 'Perl Misc' started by Erwin Waterlander, Oct 7, 2009.

  1. 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, Oct 7, 2009
    #1
    1. Advertising

  2. Op 7-10-2009 19:34, Ben Morrow schreef:
    > Quoth Erwin Waterlander <>:
    >> 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?

    >
    > 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, Oct 7, 2009
    #2
    1. Advertising

  3. 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, Oct 8, 2009
    #3
  4. Op 10/08/2009 03:00 PM, Ben Morrow schreef:
    > Quoth 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.

    >
    > 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, Oct 8, 2009
    #4
  5. Op 10/08/2009 04:50 PM, Erwin Waterlander schreef:
    > Op 10/08/2009 03:00 PM, Ben Morrow schreef:
    >> Quoth 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.

    >>
    >> 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


    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
    Erwin Waterlander, Oct 8, 2009
    #5
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Sean

    TextBox and Grave Accent

    Sean, Dec 14, 2005, in forum: ASP .Net Web Controls
    Replies:
    0
    Views:
    213
  2. phaylon

    pod2man newbie needs help

    phaylon, Feb 8, 2005, in forum: Perl Misc
    Replies:
    3
    Views:
    128
    Bill Smith
    Feb 8, 2005
  3. J Krugman
    Replies:
    4
    Views:
    204
    Steven Kuo
    Mar 9, 2005
  4. Jari Aalto

    Perlpod - How to add URL links with L<>

    Jari Aalto, Oct 8, 2009, in forum: Perl Misc
    Replies:
    1
    Views:
    191
    Jari Aalto
    Oct 8, 2009
  5. Ivan Shmakov
    Replies:
    0
    Views:
    302
    Ivan Shmakov
    Nov 23, 2013
Loading...

Share This Page