Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer
 
PerlMonks  

Better perldoc on Windows

by roho (Monsignor)
on Jun 05, 2010 at 21:35 UTC ( #843290=CUFP: print w/ replies, xml ) Need Help??

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

Example: pm File::Find

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."

Comment on Better perldoc on Windows
Select or Download Code
Re: Better perldoc on Windows
by Anonymous Monk on Jun 06, 2010 at 00:35 UTC
      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."

        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
Re: Better perldoc on Windows
by BrowserUk (Pope) 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.
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
    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.

      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...

        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.

        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.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: CUFP [id://843290]
Front-paged by Arunbear
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (5)
As of 2014-12-18 00:54 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?





    Results (41 votes), past polls