Pod::POM::Web(3)

NAME
Pod::POM::Web - HTML Perldoc server

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

STARTING THE WEB APPLICATION

  Starting from the command-line
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".

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.

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.

As a cgi-bin script

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

Other Web architectures -- PSGI

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.

  Opening a specific initial page
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

  http://localhost:8080?open=Pod/POM/Web
  http://localhost:8080?open=perlfaq

  Setting a specific title
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"

MISCELLANEOUS

  Note about security
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.

  Optional features
Syntax coloring

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.

Full-text indexing

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

Indication of the latest CPAN version

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.

HINTS TO POD AUTHORING

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

CLASS METHODS

  import
When the module is "use"d from the command-line, the "import" method automatically exports a "server" function and an "app" function to facilitate server startup.

  server
Invokes Plack::Runner to launch the server.

  app
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" or "title"
    Title for this instance of the application.

"module_dirs" or "mdirs"
    Additional directories to search for modules.

"script_dirs" or "sdirs"
    Additional directories to search for scripts.

  handler
Legacy class method, used by CGI scripts or mod_perl handlers.

  new
Constructor. May take the following arguments :

"page_title"
    for specifying the HTML title of the application (useful if you run several concurrent instances of Pod::POM::Web).

"module_dirs"
    directories for searching for modules, in addition to the standard ones installed with your perl executable.

"script_dirs"
    additional directories for searching for scripts

"script_name"
    URL fragment to be prepended before each internal hyperlink.

INSTANCE METHODS
Instance methods are not meant to be called by external clients. Some documentation can be found in the source code.

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

AUTHOR
Laurent Dami, "<dami AT cpan DOT org>"

COPYRIGHT & LICENSE
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.