perldoc works fine on Windows, but the output is raw POD, which can be a little distracting while reading. I know there is an HTML sub-directory under C:\Perl, but it is annoying to have to leave the cmd window, open Windows Explorer, drill down to the HTML path, and find the module documentation.

I wrote a two-line batch file (pm.bat) which takes a module name as input, processes the perldoc output through pod2html, saves the output in a temporary file, and displays the output as a web page. The (pm.bat) batch file is shown below:

@echo off
perldoc -m %* | pod2html > \tmp\perldoc_temp.htm & \tmp\perldoc_temp.h
+tm & del pod2htmd.tmp pod2htmi.tmp

[download]

Example: pm File::Find

[download]

I tried creating a similar batch file to display functions, but the batch file processor does NOT like the "-f" in perldoc -f ..., so I'm off to search batch file documentation to see if there is a workaround. Meanwhile, (pm.bat) is working great for displaying module documentation in HTML format.

Update

My bad, it was not the batch file objecting to "-f". perldoc displays function help as plain text, not POD, so it is not a candidate to run through pod2html.

"Its not how hard you work, its how much you get done."

Replies are listed 'Best First'.
Re: Better perldoc on Windows
by BrowserUk (Patriarch) on Jun 06, 2010 at 09:29 UTC
    I know there is an HTML sub-directory under C:\Perl, but it is annoying to have to leave the cmd window, open Windows Explorer, drill down to the HTML path, and find the module documentation.

    Hm. I find perldoc annoying full stop. -f if it's a function, except when it's log2 in which case -q. And what's that magic formulation for arctan to get pi? More importantly is that -f or -q?

    And holyshit ^C^C^C^C^C^C....<up><^end> | more<ret>

    And no keyword search unless it happens to be a word that someone already thought I might want to search for. And then only if you spell it right, cos there's no wildcarding. What! Perldoc can't do regexes?

    You could try -m grep, but with all the HTML it's mostly unintelligible. And woe betide you if your search term clashes with an html keyword. And if you're lucky enough to choose a term that finds what you need, the salient piece of information will always be on the next line without the keyword, and therefore not make it through the filter.

    My browser is always open, and in one of the tabs is the AS html. In that tab I just need to type ".keyword" and it does an intelligent--content-only, no-markup--search of the index. Eg. ".sim" finds: CGI::Simple; Hit F3 a few times and it takes me through Filter::Simple;GD::Simple; Locale::Simple; Log::Simple; LWP::Simple; ...Opt::Simplex; POD::Simple; ...Simpletree; Test::Simple; Thread::Pool::Simple; XML::Simple.

    13 keystrokes and I've seen every likely candidate for "sim".

    Of course, it's still not a full keyword search of all the content, but the next tab along is CPAN search, and it does a pretty good job for module POD contents. Shame there's no regexes.

    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    "Science is about questioning the status quo. Questioning authority".
    In the absence of evidence, opinion is indistinguishable from prejudice.
[reply]
Re: Better perldoc on Windows
by Anonymous Monk on Jun 06, 2010 at 00:35 UTC
[reply]
      Installed Pod::Server. It failed to run because it couldn't locate Coro/Cont.pm. Installed Coro. Still no joy. Neither ppm nor cpan command could find Coro::Cont. (Anyone know what Coro::Cont is, and where it is?) Frustrating, compared with the 1 to 2 minutes required to enter and run the two-line batch file. Thanks anyway.

      "Its not how hard you work, its how much you get done."

[reply]
        Coro::Cont used to be part of Coro... Pod-Server-1.10 doesn't use it anymore.

        Frustrating, compared with the 1 to 2 minutes required to enter and run the two-line batch file. Thanks anyway.

        I personally use tkpod or Perldoc::Server, but if you want batchery, try ap-user-guide 

        @rem = '--*-Perl-*--
@echo off
if "%OS%" == "Windows_NT" goto WinNT
perl -x -S "%0" %1 %2 %3 %4 %5 %6 %7 %8 %9
goto endofperl
:WinNT
perl -x -S %0 %*
if NOT "%COMSPEC%" == "%SystemRoot%\system32\cmd.exe" goto endofperl
if %errorlevel% == 9009 echo You do not have Perl in your PATH.
if errorlevel 1 goto script_failed_so_exit_with_non_zero_val 2>nul
goto endofperl
@rem ';
#!/usr/bin/perl -w
#line 15

use strict;
use Config qw(%Config);

my $htmldir = $Config{installhtmldir} || "$Config{prefix}/html";
my $index = "$htmldir/index.html";

die "No HTML docs installed at $htmldir\n"
    unless -f $index;

require ActiveState::Browser;
ActiveState::Browser::open($index);

__END__

=head1 NAME

ap-user-guide - open the ActivePerl User Guide in you browser

=head1 SYNOPSIS

B<ap-user-guide>

=head1 DESCRIPTION

This script opens up the "ActivePerl User Guide" in your web browser.
The user guide will not be available if ActivePerl was installed
without the HTML documentation.  If that's the case you can still use
the L<perldoc> command to read the core documentation and manpages for
the installed modules.

The script does not take any command line options.

=head1 ENVIRONMENT

Set the C<AS_BROWSER> environment variable to override what browser to
use.  See L<ActiveState::Browser> for details.

=head1 SEE ALSO

L<perldoc>, L<ActiveState::Browser>

__END__
:endofperl

        [download]
[reply]
[d/l]
Re: Better perldoc on Windows
by Jenda (Abbot) on Jun 06, 2010 at 19:54 UTC

    Let me copy&paste some text from my homenode here:

    If you're using Windows and find the default perldoc display suboptimal you may try this doskey macro 

    pdoc=perldoc -o html -T -w index $* > %TEMP%\perldoc_temp.html && star
+t %TEMP%\perldoc_temp.html

    [download]
    If you then use pdoc Module::Name instead of perldoc Module::Name you get the docs formatted as HTML in a browser window. It's best to store the macro(s) in a file and start the Command Prompt via a shortcut like this: %windir%\System32\cmd.exe /F:ON /k doskey /macrofile="%USERPROFILE%\doskey.mac"

    Jenda
    Enoch was right!
    Enjoy the last years of Rome.

[reply]
[d/l]
[select]
      To my surprise, I'm learning from this discussion that win consoles can't display the formats necessary for manpages (bold, italics ,...), but this workaround of opening a browser-window doesn't seem to be much within CLI philosophy nor fast...

      So what about installing lynx or w3m on windows to display html?

      Cheers Rolf

      PS: Sorry for my Win-ignorance, but I have to admit I'm never running into these kinds of problems .... one of the benefits of using emacs on each OS-plattform...

[reply]

        I'd much rather wait the halfsecond necessary to open the additional browser window that block my console and have to put up with the restrictive more or less or whatever pager you decide to use. I tend to display the manpages of a few modules at a time and switch between them at will.

        Jenda
        Enoch was right!
        Enjoy the last years of Rome.

[reply]

        I found this quote from a "how to write man pages" course instructive:

        If Unix was being invented now, man pages would probably be written using HTML, the Hypertext Mark-up Language for World Wide Web pages ...
        Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
        "Science is about questioning the status quo. Questioning authority".
        In the absence of evidence, opinion is indistinguishable from prejudice.
[reply]

Back to Cool Uses for Perl