Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

Better perldoc on Windows

by roho (Canon)
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."

Replies are listed 'Best First'.
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 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 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?
[hippo]: Understood. I'll have to go through the code and see if it's doing anything fancy with ties, dual-vars or non-scalars. In the end, it's probably a bug though.
[Corion]: Aaah - you should be able to do this with overload, but I would hit somebody really hard if they constructed objects that are true but the empty string, and you not knowing about the domain knowledge where this makes sense
[Eily]: you could tie a variable into not having the same value each time, if you like to make people who try to debug your code facepalm
[Corion]: perl -wle 'package o; use overload q("") => sub {warn "str"; ""}, bool => sub{warn "bool"; 1}; package main; my $o={}; bless $o => o; print "Yay" if ($o && !length($o))'
[Corion]: But people writing such code should document the objects they construct and why it makes sense for an object to be invisible as string while being true in a boolean context
[hippo]: That's equal parts clever and horrendous.
[Eily]: the overload version wouldn't return true with "$x" && !length $x though, I guess
[hippo]: The more I look at this code, the more $x is a plain old scalar and the more this condition will never be true. I'm calling it a bug at this point.
[hippo]: Thanks for your input which has soothed my sanity (a little)
[Corion]: Eily: Sure - if you force both things into stringy things, then you break that magic. But that would also mean that you changed the expression, as now $x = 0.00 will be true instead of false as it were before

How do I use this? | Other CB clients
Other Users?
Others about the Monastery: (14)
As of 2017-07-27 13:38 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    I came, I saw, I ...
























    Results (413 votes). Check out past polls.