/ 
Pod-POM-Web-1.27
River stage one • 2 direct dependents • 2 total dependents
7 ++
/ Pod::POM::Web

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

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