- STARTING THE WEB APPLICATION
- HINTS TO POD AUTHORING
- CLASS METHODS
- INSTANCE METHODS
- COPYRIGHT & LICENSE
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
Another way to start the server is to call
plackup directly :
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 :
#!/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
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.
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
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.
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">
=for html <object type="image/svg+xml" data="try.svg" width="640" height="480"> </object>
Here it is assumed that auxiliary files
try.svg are in the same directory than the POD source; but of course relative or absolute links can be used.
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.
Invokes Plack::Runner to launch the server.
Creates an instance of the module and returns a PSGI app.
Title for this instance of the application.
Additional directories to search for modules.
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
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.
<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.