Pod::POM::Web - HTML Perldoc server
Pod::POM::Web is a Web application for browsing the documentation of Perl components installed on your local machine. Since pages are dynamically generated, they are always in sync with code actually installed.
The application offers
a tree view for browsing through installed modules (with dynamic expansion of branches as they are visited)
a tree view for navigating and opening / closing sections while visiting a documentation page
a source code view with hyperlinks between used modules and optionally with syntax coloring (see section "Optional features")
direct access to perlfunc entries (builtin Perl functions)
search through perlfaq headers
full-text search, including names of Perl variables (this is an optional feature -- see section "Optional features").
parsing and display of version number
display if and when the displayed module entered Perl core.
parsing pod links and translating them into hypertext links
links to MetaCPAN
The application may be hosted by an existing Web server, or otherwise may run its own builtin Web server. Instructions for launching the application are given in the next section.
Usage of the application is described in a separate document Pod::POM::Web::Help.
The simplest way to use this application is to start a process invoking the builtin HTTP server :
perl -MPod::POM::Web -e server
This is useful if you have no other HTTP server, or if you want to run this module under the perl debugger. The server will listen at http://localhost:5000. A different port may be specified :
perl -MPod::POM::Web -e server -- -p 8888
Notice the double dash -- : this is used to separate options to the perl command itself from options to Pod::POM::Web.
--
perl
Pod::POM::Web
The internal implementation of server is based on Plack::Runner, the same module that also supports the plackup utility. All plackup options can also be used here -- see plackup's documentation.
server
Another way to start the server is to call plackup directly :
plackup
plackup -MPod::POM::Web -e app -p 8888
In this case no double dash is required.
Alternatively, you can run this application as a cgi-script by writing a simple file perldoc in your cgi-bin directory, containing :
cgi-bin
#!/path/to/perl use Pod::POM::Web; use Plack::Handler::CGI; my $app = Pod::POM::Web->new->to_app; Plack::Handler::CGI->new->run($app);
For historical reasons, the module also supports a simpler invocation, written as follows :
#!/path/to/perl use Pod::POM::Web; Pod::POM::Web->handler;
Make this script executable, then navigate to URL http://localhost/cgi-bin/perldoc.
The application is built on top of the well-known Plack middleware for web applications, using the PSGI protocol. Therefore it can be integrated easily in various Web architectures. Write a .psgi file as follows :
use Pod::POM::Web; Pod::POM::Web->new->to_app;
and invoke one of the Web server adapters under Plack::Handler.
By default, the initial page displayed by the application is perl. This can be changed by supplying an open argument with the path to any documentation page: for example
open
http://localhost:8080?open=Pod/POM/Web http://localhost:8080?open=perlfaq
If you run several instances of Pod::POM::Web simultaneously, you may want them to have distinct titles. This can be done like this:
perl -MPod::POM::Web -e server -- --title "My Own Perl Doc"
This application is intended as a power tool for Perl developers, not as an Internet application. It will give read access to any file installed under your @INC path or Apache lib/perl directory; so it is probably a bad idea to put it on a public Internet server.
@INC
lib/perl
Syntax coloring improves readability of code excerpts. If your Perl distribution is from ActiveState, then Pod::POM::Web will take advantage of the ActiveState::Scineplex module which is already installed on your system. Otherwise, you need to install PPI::HTML, available from CPAN.
Pod::POM::Web can index the documentation and source code of all your installed modules, including Perl variable names, Names:::Of::Modules, etc. To use this feature you need to
Names:::Of::Modules
install Search::Indexer from CPAN
build the index as described in Pod::POM::Web::Indexer documentation.
When displaying a module, CPAN::Common::Index is used to try to identify the latest CPAN version of that module. By default the information comes from http://cpanmetadb.plackperl.org/v1.0/, but it requires an internet connection. If a local installation of CPAN::Mini is available, this will be used as a primary source of information.
http://cpanmetadb.plackperl.org/v1.0/
The Pod::Pom::Web server also serves non-pod files within the @INC hierarchy. This is useful for example to include images in your documentation, by inserting chunks of HTML as follows :
=for html <img src="pretty_diagram.jpg">
or
=for html <object type="image/svg+xml" data="try.svg" width="640" height="480"> </object>
Here it is assumed that auxiliary files pretty_diagram.jpg or try.svg are in the same directory than the POD source; but of course relative or absolute links can be used.
pretty_diagram.jpg
try.svg
When the module is used from the command-line, the import method automatically exports a server function and an app function to facilitate server startup.
use
import
app
Invokes Plack::Runner to launch the server.
Creates an instance of the module and returns a PSGI app.
Options from the command-line that are not consumed by plackup are read and passed to to the new method. Available options are :
page_title
title
Title for this instance of the application.
module_dirs
mdirs
Additional directories to search for modules.
script_dirs
sdirs
Additional directories to search for scripts.
Legacy class method, used by CGI scripts or mod_perl handlers.
Constructor. May take the following arguments :
for specifying the HTML title of the application (useful if you run several concurrent instances of Pod::POM::Web).
directories for searching for modules, in addition to the standard ones installed with your perl executable.
additional directories for searching for scripts
script_name
URL fragment to be prepended before each internal hyperlink.
Instance methods are not meant to be called by external clients. Some documentation can be found in the source code.
This web application was deeply inspired by :
the structure of HTML Perl documentation released with ActivePerl (http://www.activeperl.com/ASPN/Perl).
the excellent tree navigation in Microsoft's former MSDN Library Web site -- since they rebuilt the site, keyboard navigation has gone !
the standalone HTTP server implemented in Pod::WebServer.
the wide possibilities of Andy Wardley's Pod::POM parser.
Thanks to Philippe Bruhat who mentioned a weakness in the API, to Chris Dolan who supplied many useful suggestions and patches, to Rémi Pauchet who pointed out a regression bug with Firefox CSS, to Alexandre Jousset who fixed a bug in the TOC display, to Cédric Bouvier who pointed out a IO bug in serving binary files, to Elliot Shank who contributed the "page_title" option, to Olivier 'dolmen' Mengué who suggested to export "server" into main::, to Ben Bullock who added the 403 message for absent modules, and to Paul Cochrane for several improvements in the doc and in the repository structure.
main::
Laurent Dami, <dami AT cpan DOT org>
<dami AT cpan DOT org>
Copyright 2007-2021 Laurent Dami, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Pod::POM::Web, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::POM::Web
CPAN shell
perl -MCPAN -e shell install Pod::POM::Web
For more information on module installation, please visit the detailed CPAN module installation guide.