http://www.perlmonks.org?node_id=1081048

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

I'm new to Perl and am trying to figure out how to use POD.

First, some important "stuff": OS: Windows 7 on my desktop and Ubuntu 1204 on my laptop (I use both somewhat interchangeably). Perl: Strawberry 5.18 on Windows, 5.14 on Linux. IDE: Padre and Eclipse/Epic (both loaded on each platform, and I alternate between them).

I've created just a tiny POD sample:

#!/usr/bin/perl print "Hello, World!\n"; =head1 NAME My::Module - An example module =cut

When I run the program, "Hello, World!" prints properly; the POD stuff is ignored (as I expect). However, how can I view the documentation?

I've tried running perldoc in a terminal with the name of the script as an argument: perldoc hello.pl -- but that doesn't seem to work.

I created a separate .POD file with some documentation and this did work: perldoc hello.pod. However, is there some way to view the documentation that's embedded in a script? Ideally, I'd like to embed the POD documentation at the bottom of a script and then click something or enter something to view that documentation from within either IDE.

Thanks, in advance, for any help you can offer.

Replies are listed 'Best First'.
Re: How To View POD Embedded in a Perl Script?
by LanX (Saint) on Apr 04, 2014 at 01:09 UTC
    POD requires (per specification) empty lines around the delimiters. Some parsers don't care but it's usually better.

    #!/usr/bin/perl print "Hello, World!\n"; =head1 NAME My::Module - An example module =cut

    please note the newline after cut.

    Using perldoc is ok

    update

    concerning IDEs: emacs in cperl-mode has the cperl-pod-to-manpage command, also available via menu as Perl / Perl docs / View manpage of POD in this file

    Cheers Rolf

    ( addicted to the Perl Programming Language)

      Thanks for your help. For what it's worth, I actually did RTFM and knew that there was supposed to be a blank line following cut. I had a CR at the end of the cut line so the cursor jumped to a new line for input and I stupidly thought that was a blank line. It was not. I entered a CR on the line following cut in order to get a true blank line and the pod documentation is now working fine.

      I also found out that in Padre on Windows I could enter "perldoc pod.pl" as a Run -> Run Command (or Ctrl+F5) and the documentation displayed just fine. I'm still working making this work with Eclipse (I think that I have to define a new External Tool) and on my Linux box (I have to install the perl-doc package).

      However, I'm over that first hurdle. Thanks, again, for your help.

        IMHO running commands and piping STDOUT into a pane is a generic feature of every editor (or at least IDE).

        I'd be surprised if Padre or EPIC (i.e. Eclipse) do not already provide preset hotkeys. (maybe try F-keys in combination with Ctrl or Alt)

        Cheers Rolf

        ( addicted to the Perl Programming Language)

Re: How To View POD Embedded in a Perl Script?
by Anonymous Monk on Apr 04, 2014 at 01:47 UTC

      The problem was my improper coding of the pod block. I failed to put a blank line at the end. Thanks for your help.

Re: How To View POD Embedded in a Perl Script?
by Laurent_R (Canon) on Apr 04, 2014 at 06:16 UTC
Re: How To View POD Embedded in a Perl Script?
by Discipulus (Canon) on Apr 04, 2014 at 09:48 UTC
    When you are on win you can also benefit of Jenda's useful macro:
    pdoc=perldoc -o html -T -w index $* > %TEMP%\perldoc_temp.html && star +t %TEMP%\perldoc_temp.html
    HtH*
    There are no rules, there are no thumbs..
    Reinvent the wheel, then learn The Wheel; may be one day you reinvent one of THE WHEELS.

      Thanks for the tip, and the link. I'll play around with this doskey macro to see if I like the HTML display better than the default perldocs display.

Re: How To View POD Embedded in a Perl Script?
by ParsonGeorge (Initiate) on Apr 04, 2014 at 13:42 UTC

    Woa! I just now stumbled upon a great Padre feature. I clicked Help->Current Document and the pod documentation popped up in a new window (worked on both Windows and Ubuntu). Just wanted to add this note in case anyone else is struggling with displaying pod for your program.