proper shell term/TERM value for windows in XQuartz?

I'm looking for the proper setting for $term/$TERM for use in windows in XQuartz. Neither xterm nor vt100 work well. They do display plain text okay, but they have trouble when I try to use some non-plain text.

man pages usually display okay, but sometimes they have problems. (Unfortunately, I can't think of a good bad example at the moment.)

Right now, I'm seeing this when I try to display POD. Here's some simple pod and some perldoc runs with different $term settings:

iolaire(100)> cat podtest
#!/usr/bin/env perl

1;

=pod

=head1 NAME

B<podtest> - podtest for pod output on shell

=head1 SYNOPSIS

  podtest

=head1 DESCRIPTION

B<podtest> is pod test.

=cut

iolaire(101)> set term=vt100
iolaire(102)> perldoc podtest
2ESC[1mNAME2ESC[0m
    2ESC[1mpodtest2ESC[0m - podtest for pod output on shell

2ESC[1mSYNOPSIS2ESC[0m
      podtest

2ESC[1mDESCRIPTION2ESC[0m
    2ESC[1mpodtest2ESC[0m is pod test.

iolaire(103)> set term=xterm
iolaire(104)> perldoc podtest
iolaire(105)> perldoc podtest | cat -v
^[[1mNAME^[[0m
    ^[[1mpodtest^[[0m - podtest for pod output on shell

^[[1mSYNOPSIS^[[0m
      podtest

^[[1mDESCRIPTION^[[0m
    ^[[1mpodtest^[[0m is pod test.

iolaire(106)>

I have had the same problem in tcsh and in bash.

Perldoc used to work fine on xterms on OSX. A few years ago this behavior started and I've finally gotten fed up with it and am trying to get it working again. (Perldoc, some man pages, and um, a few other things in which I've seen this problem.)

Thanks so much for the help!

versions: XQuartz 2.7.11; OSX 10.13.4; Perl v5.26.2; Perldoc v3.28

Solution

short: the problem is likely in how your pager (e.g., less) is being invoked.

long: perldoc uses hard-coded escapes via Pod::Text::Color and in turn Term::ANSIColor, e.g.,

# Make level two headings bold.
sub cmd_head2 {
    my ($self, $attrs, $text) = @_;
    $text =~ s/\s+$//;
    $self->SUPER::cmd_head2 ($attrs, colored ($text, 'bold'));
}

# Fix the various formatting codes.
sub cmd_b { return colored ($_[2], 'bold')   }
sub cmd_f { return colored ($_[2], 'cyan')   }
sub cmd_i { return colored ($_[2], 'yellow') }

# Output any included code in green.
sub output_code {
    my ($self, $code) = @_;
    $code = colored ($code, 'green');
    $self->output ($code);
}

and since all of the moving parts are buried away within the perl library, there's not much that you could have done to break this. Unlike a few other perl modules, this one appears to ignore the value for TERM.

On the other hand, perldoc uses for pager. It's manual page says

   "perldoc" will use, in order of preference, the pager defined in
   "PERLDOC_PAGER", "MANPAGER", or "PAGER" before trying to find a pager
   on its own. ("MANPAGER" is not used if "perldoc" was told to display
   plain text or unformatted pod.)

If you happened to set PAGER to less, then it will use that value. But less will display escape characters as shown in your example unless you add an option to the command, e.g., -R. Doing that to PAGER is likely to interfere with other applications, so perldoc looks first for its own variable PERLDOC_PAGER.