Pdoc: driver scripts

Pdoc release: 1.1

Raphaël Leplae © 2000-2006
Driver scripts

News

Back

Driver scripts

The Pdoc alone won't do very much. Scripts need to be written to use the lib for transforming once set of files into a new format.
Only one driver script is currently available:

Script	Description	Download	Examples
perlmod2www.pl	Transforms a Perl library directory tree to an HTML tree.	In the script directory of the Pdoc package	Examples

perlmod2www.pl

For quick access to the documentation, execute the script with the '-h' option.

perlmod2www.pl converts Perl packages/modules into HTML format.
The script gets a path where Perl modules are located (-source) and a path where to create the HTML pages (-target). The target directory must exists.
A number of extra options can be used as follow:

-wroot: each link to other pages in the HTML tree are created as relative path. If you want to create links for a specific site, define the -wroot option with the url where the top HTML tree will be accessible (note: remember to put the url between single quotes).
-style: defines the rendering style. Values are 'css' (default) or 'html'. If set to 'html', basic html rendering will be used but this won't be supported anymore in the future!
-css: defines the path to an alternate CSS file with the styles definition. If not set, it will be automatically defined based on the Pdoc lib installation path.
-css_url: defines the url to use for accessing the CSS file. If set the -css option will be ignored.
-skip: while parsing the Perl dir tree, you can skip specific directories with the -skip <dir,dir2,dir3,...> option. By default the 'CVS' directories will be skipped.
-doc_header and/or -doc_footer: to add a piece of HTML code on top or at the bottom of every Perl module HTML pages, use the -doc_header or -doc_footer and a file name with the HTML code as argument.
-xl: one very nice feature is the cross-linking between different documented Perl libraries. Use the -xl option to define one cross-link parameter, use several -xl options for serveral libs to cross-link. The -xl argument is in two parts separated by a comma. The first part is the root path of the Perl lib to search for cross-linking and the second part is the root url where is located the documented lib for the cross-linking. The url can be absolute (http://...) or relative to the created HTML tree. For example 'Lib1' has been documented and is located in /usr/local/html/pdoc/Lib1. 'Lib2' is now documented in /usr/local/html/pdoc/Lib2. To cross-link it, the relative url will be ../.
-xltable: if you have many libraries to cross-link, use the -xltable option with the file name containing the cross-linkig data. The file format is simple, one line by cross-linkng data. Each line containing the lib root path and root url separated by a space.
-webcvs: if the documented Perl lib is under CVS and that the CVS tree is under the WebCVS cgi-bin, you can use the -webcvs with the cgi-bin url. For example if the url to access the package My::Lib::MyMod is 'http://www.mysite.org/cgi-bin/webcvs.cgi?/cvsroot/My/Lib/MyMod' the -webcvs argument will be 'http://www.mysite.org/cgi-bin/webcvs.cgi?/cvsroot/'.
-nosort: by default the methods/subroutines in a Perl module/package are sorted alphabetically, to remove that feature, use the -nosort.
-isa: a toy feature is the -isa. If passed to the script, every package defined in the @ISA variable not found in the Perl lib directory tree will generate a warning message.
-conf: to customise how the various bits and pieces of the Perl modules are transformed into HTML format, use the -conf with a config file. Either check the pdoc/data/config.example file or look in the Pdoc library documentation for modules having the 'config' method.

Examples

In these examples, the following are assumed:

The Perl modules to be rendered are located in /home/me/MyLib/
The web server root path located in /home/www/htdocs/
And the Pdoc rendered documentation path located in /home/www/htdocs/pdoc/MyLib/ and already created.
The web site being www.mysite.org and therefore the rendered lib will be in www.mysite.org/pdoc/MyLib.

A very basic example being:

perlmod2www.pl -source /home/me/MyLib/ -target /home/www/htdocs/pdoc/MyLib/

This should be sufficient to get your Perl modules properly rendered and visible either directly through a web browser (open the /home/www/htdocs/pdoc/MyLib/index.html file) or via your web server (www.mysite.org/pdoc/MyLib).

The perlmod2www.pl script skips by default the CVS and blib dirctories. You can skip others using the -skip option:

perlmod2www.pl -source /home/me/MyLib/ -target /home/www/htdocs/pdoc/MyLib/ -skip SubDir1,SubDir2

In this case, the sub-directories SubDir1 and SubDir2 (wherever they are) will be skipped.

You can prepare the documentation for a specific site using the -wroot option:

perlmod2www.pl -source /home/me/MyLib/ -target /home/www/htdocs/pdoc/MyLib/ -wroot 'http://some.other.site/development/pdoc/MyLib'

In this case, all the links generated in the html files will be based on the http://some.other.site/development/pdoc/MyLib location.

You can place the Pdoc/Html/Data/perl.css file in some specific location on your server and refer to such file when generating the documentation:

perlmod2www.pl -source /home/me/MyLib/ -target /home/www/htdocs/pdoc/MyLib/ -css_url /css/perl.css

In this case, all the generated html files will use the /css/perl.css url to get the CSS file. This imply that the Pdoc/Html/Data/perl.css file has been copied, in this example, to /home/www/htdocs/css/ server directory.

You can use alternate CSS files as the default proposed in Pdoc too:

perlmod2www.pl -source /home/me/MyLib/ -target /home/www/htdocs/pdoc/MyLib/ -css /home/me/my_perl.css

In this case, the /home/me/my_perl.css will be used to produce the /home/www/htdocs/pdoc/MyLib/perl.css file.

If a Perl library is using modules from another library (let say /home/me/OtherLib/), than you can render such library too and cross-link the two on the server:

perlmod2www.pl -source /home/me/OtherLib/ -target /home/www/htdocs/pdoc/OtherLib/

perlmod2www.pl -source /home/me/MyLib/ -target /home/www/htdocs/pdoc/MyLib/ -xl /home/me/OtherLib,/home/www/htdocs/pdoc/OtherLib

The first line generates the OtherLib documentation, the second line will cross-link any module from OtherLib used in MyLib. The -xl option gets the original source code path and the target html path separated by a comma as argument. See also the -xltable option to specify a file with a list of cross-references in case there are too much for one single command line.

You can add a personalised touch to the rendered documentation using a specific header and/or footer to the web pages:

perlmod2www.pl -source /home/me/MyLib/ -target /home/www/htdocs/pdoc/MyLib/ -doc_header /home/me/my_header.html -doc_footer /home/me/my_footer.html

Each top and bottom rendered page will get the piece of HTML code defined in the files /home/me/my_header.html and /home/me/my_footer.html respectively.

There are some extra data that can be added to the rendered Perl module pages accessible via a toolbar created in these pages:

perlmod2www.pl -source /home/me/MyLib/ -target /home/www/htdocs/pdoc/MyLib/ -webcvs '/cgi/webcvs.cgi' -raw

With the -webcvs option, a WebCvs link will be added in the toolbar to access the module CVS status, provided that webcvs has been installed and handles the library under a CVS repository. The -raw option will add a RawContent link to view the Perl module content in plain text.

Back