Perl podusage generates man page with extra control-O's

Question

I am using pod2usage in a Perl script to generate a man page. The code looks like this:

use Pod::Usage;
pod2usage(-verbose => 2) ;
exit 0 ;
... some code ...
__END__                                                                                                                             

=head1 NAME                                                                                                                         

my-program - program to do things                                                                   

=head1 SYNOPSIS                                                                                                                     

B<my-program> ( help | status | version )                                                                              

B<my-program> ( lock I<reason> )                                                                                                

B<my-program> ( unlock [I<username | ALL>] ) 

When I run the program I get the man page but it looks like this:

NAME^O
    my-program - program to do things

SYNOPSIS^O
    my-program^O ( facter | help | status | version )

    my-program^O ( lock reason^O )

    my-program^O ( unlock [username | ALL^O] )

In the above, the words are bold-faced and underlined but have these ^O's following them. Why are they there?

Note that if I do a simple man page (e.g., man man) the words that are bold-faced or underlined do not have ^O suffixed.

This is happening on a Debian stretch machine in a bash shell with the term variable set to linux.

Answer 1

I can (surprisingly) reproduce your issue on OpenBSD with TERM set to linux (or rxvt). With TERM set to vt100, screen, tmux, xterm or other common terminals, I have no issue and the ^O characters do not show up.

The only relevant information that I've been able to find relating to terminal capabilities is that Pod::Text, which Pod::Usage uses, used to use termcap sequences before it was rewritten. With TERM=linux, it doesn't seem to make any difference if Pod::Usage is using the default Pod::Text for formatting, or if it's made to use the Pod::Text::Termcap as explained in the Pod::Usage documentation:

The default text formatter is Pod::Text. The base class for Pod::Usage can be defined by pre-setting $Pod::Usage::Formatter before loading Pod::Usage, e.g.:

BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
use Pod::Usage qw(pod2usage);

Make sure that your TERM variable is correctly set for the terminal that you are using. Most terminas work well with either xterm or xterm-color, although sessions running in screen or tmux should have TERM=screen (both programs enforces this by default).