pod2usage width

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

I have a small perl module, and am using Getopt::Long, and I figured I might as well use Pod::Usage to get a nice looking help display.

After some fiddling, I got it to work reasonably well, with one minor exception. I can't set the width of the output.

My terminal is 191 characters wide. Using perldoc Test.pm, it correctly formats the documentation to that width. Using pod2usage(), it uses the default width of 76 characters.

I can't figure out how to get the width option passed in to the formatter. The documentation shows how to set a different formatter (such as Pod::Text::Termcap) using a BEGIN block, and I used Term::ReadKey to pull the width (verified), but I just can't get the formatter to see it.

Any hints?

package Test;
BEGIN {
    use Term::ReadKey;

    my ($width, $height, $pixel_width, $pixel_height) = GetTerminalSiz
+e();
    #print "WIDTH: $width\n";
    $Pod::Usage::Formatter = 'Pod::Text::Termcap';
    $Pod::Usage::width = $width;
}

use Pod::Usage;
use Pod::Find qw(pod_where);

# stuff

GetOptionsFromArray( \@args ,
        'help|?'        => sub { pod2usage( -width => $width, -input =
+> pod_where( {-inc => 1}, __PACKAGE__), -exitval => 1 ); },
        'man'           => sub { pod2usage( -input => pod_where( {-inc
+ => 1}, __PACKAGE__), -exitval => 2, -verbose => 2 ); },
);
[download]

Comment on pod2usage width Download Code

Replies are listed 'Best First'.
Re: pod2usage width (OT) by ww (Archbishop) on Oct 13, 2013 at 11:50 UTC
OT Fergeddiboudit! :-) OT, but as serious as death: reading and comprehending any document displayed at your requested length (possible exception: spreadsheets or other data using multi-column records) is generally more difficult that with shorter (much shorter) displayed-width. Imagine, if you will trying to read (or even just scan) a newpaper in which the text of each story occupies the full width of the page. Consider all the (recent) research on the relationship between line length and readability or - without the academic overburden -- try, for example, one of the practicality-oriented hits from big G. For a more exhaustive list, search on "readability relationship to width" ( https://www.google.com/search?q=readability+relationship+to+width ) Update/afterthought: I realize there's 'no accounting for taste' but unless you're the only user of this module, you might want to rethink your plan, on behalf of other users who may prefer 76 chars or have a narrower window to read your docs.	[reply]

Replies are listed 'Best First'.

Re: pod2usage width (OT)
by ww (Archbishop) on Oct 13, 2013 at 11:50 UTC

:-)

OT, but as serious as death: reading and comprehending any document displayed at your requested length (possible exception: spreadsheets or other data using multi-column records) is generally more difficult that with shorter (much shorter) displayed-width. Imagine, if you will trying to read (or even just scan) a newpaper in which the text of each story occupies the full width of the page. Consider all the (recent) research on the relationship between line length and readability or - without the academic overburden -- try, for example, one of the practicality-oriented hits from big G. For a more exhaustive list, search on "readability relationship to width" ( https://www.google.com/search?q=readability+relationship+to+width )

Update/afterthought: I realize there's 'no accounting for taste' but unless you're the only user of this module, you might want to rethink your plan, on behalf of other users who may prefer 76 chars or have a narrower window to read your docs.

[reply]