Beefy Boxes and Bandwidth Generously Provided by pair Networks
good chemistry is complicated,
and a little bit messy -LW
 
PerlMonks  

[SOLVED]: Binary File warning when using POD documentation

by amcleod (Novice)
on Sep 05, 2021 at 15:55 UTC ( [id://11136469]=perlquestion: print w/replies, xml ) Need Help??

amcleod has asked for the wisdom of the Perl Monks concerning the following question:

A minor, but annoying issue:

I want to start using POD documentation in my projects, but the simplest attempt results in a warning message when trying to display the documentation:

Pressing Y displays the documentation as expected. Pressing ENTER twice causes output to be displayed with the ANSI sequences munged by removing the ESC characters.

$ perldoc perltest "/tmp/dACGXRf5qF" may be a binary file. See it anyway? more: unknown option -R Usage: more [options] <file>... A file perusal filter for CRT viewing. Options: -d display help instead of ringing bell -f count logical rather than screen lines -l suppress pause after form feed -c do not scroll, display text and clean line ends -p do not scroll, clean screen and display text -s squeeze multiple blank lines into one -u suppress underlining -<number> the number of lines per screenful +<number> display file beginning from line number +/<string> display file beginning from search string match -V display version information and exit For more details see more(1). "/tmp/dACGXRf5qF" may be a binary file. See it anyway? ?[1mNAME?[0m The quick brown fox jumps over the lazy dog. ?[1mSYNOPSIS?[0m The quick brown fox jumps over the lazy dog. ?[1mDESCRIPTION?[0m The quick brown fox jumps over the lazy dog. ?[1mAUTHOR?[0m The quick brown fox jumps over the lazy dog.

Note the '?' characters where the ESC characters would be expected. And here is the simple program I am using to test:

#!/usr/bin/perl -w use feature 'say'; =head1 NAME The quick brown fox jumps over the lazy dog. =head1 SYNOPSIS The quick brown fox jumps over the lazy dog. =head1 DESCRIPTION The quick brown fox jumps over the lazy dog. =head1 AUTHOR The quick brown fox jumps over the lazy dog. =cut say "Testing..."; exit;

I can see no reason for the resulting documentation to be considered binary. The only think in the output that I can see that is even close are the ESC characters in the ANSI sequences and they are simple control characters, which I doubt are an issue for the terminal. Running perldoc perlpod produces nothing on the matter. Googling has turned up no suggestions, far less answers.

Sure, I can just press Y and the documentation is displayed, but that is simply accepting the issue instead of trying to correct it.

Anyone got an idea what I'm doing wrong, or how this can be solved?

(By the way, I occasionally see this same behaviour with other POD documentation from other sources, but it is thankfully rare.)

Replies are listed 'Best First'.
Re: Binary File warning when using POD documentation
by LanX (Saint) on Sep 05, 2021 at 16:07 UTC
    Hi

    Your terminal/pager is different than expected by perldoc.

    This can be configured as an option at startup or with various ENV variables named PERLDOC*.

    I'd recommend reading this recent threads perldoc Bold, Italic etc, especially Re: perldoc Bold, Italic etc (updated) and of course the linked docs.

    My guess perldoc -oman should fix it.

    Update

    > (By the way, I occasionally see this same behaviour with other POD documentation from other sources, but it is thankfully rare...

    This sounds like an encoding issue or (less likely) OS specific line ending.

    Please compare those files to find the differences.

    update

    perldoc -l shows the path

    perldoc -m will cat original code

    Cheers Rolf
    (addicted to the Perl Programming Language :)
    Wikisyntax for the Monastery

      After reading through the references you suggested and trying various proposed solutions, I corrected the issue by inserting

      export PERLDOC_PAGER="less -isR"
      into my ~/.bashrc file. Now I will attempt to mark this as "SOLVED".

        Glad it helped! :)

        Actually perldoc should work out of the box on every *nix OS. And your random results look weird.

        But of course there are plenty of ways to mess up.

        If you are curious to find out, you might consider running tests with -D and PERLDOCDEBUG set to a positiv value

        Cheers Rolf
        (addicted to the Perl Programming Language :)
        Wikisyntax for the Monastery

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlquestion [id://11136469]
Approved by haukex
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others lurking in the Monastery: (5)
As of 2024-04-25 15:38 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found