-
-
02 Jul 2021 07:10:05 UTC
- Distribution: Pod-POM-Web
- Module version: 1.27
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues (0)
- Testers (50 / 1 / 0)
- Kwalitee
Bus factor: 1- % Coverage
- License: perl_5
- Perl: v5.10.0
- Activity
24 month- Tools
- Download (37.97KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Alien::GvaScript
- CPAN::Common::Index
- CPAN::Common::Index::Mux::Ordered
- Config
- Encode
- List::MoreUtils
- List::Util
- MIME::Types
- Module::CoreList
- Module::Metadata
- POSIX
- Params::Validate
- Path::Tiny
- Plack::Request
- Plack::Response
- Plack::Util
- Pod::POM
- Pod::POM::View::HTML
- Search::Indexer
- Time::HiRes
- URI
- URI::QueryParam
- parent
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- DESCRIPTION
- STARTING THE WEB APPLICATION
- MISCELLANEOUS
- HINTS TO POD AUTHORING
- CLASS METHODS
- INSTANCE METHODS
- ACKNOWLEDGEMENTS
- AUTHOR
- COPYRIGHT & LICENSE
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 theperl
command itself from options toPod::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 examplehttp://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 Apachelib/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 toinstall 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
ortry.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, theimport
method automatically exports aserver
function and anapp
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
ortitle
-
Title for this instance of the application.
module_dirs
ormdirs
-
Additional directories to search for modules.
script_dirs
orsdirs
-
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.
Module Install Instructions
To install Pod::POM::Web, copy and paste the appropriate command in to your terminal.
cpanm Pod::POM::Web
perl -MCPAN -e shell install Pod::POM::Web
For more information on module installation, please visit the detailed CPAN module installation guide.