|
Version 1.1
|
|
Moved to cascading style sheets (CSS).
|
The use of CSS in Pdoc has been implemented.
Almost all the styles used in the generated HTML pages rely on CSS, including the Perl source code, the POD and in the general page layouts. The definitions are stored in a perl.css file located in the pdoc-xxx/Pdoc/Html/Data/ directory. The perldoc2www.pl script has two new options (-css and -css_url) to specify alternate ways of using a CSS file. See the Scripts section for more details. The plain old HTML style is still available but not supported anymore.
|
|
Version 1.0
|
|
Final design of the library.
|
The Pdoc library design seems quite ok and no major changes should happen for a while. The energy is now to be put in the addition of new features such as new formats pasring and new formats conversion.
|
|
Platforms
|
The Pdoc library can be used on UNIX. For MSWindows and Mac platforms, some work need to be done for the system compatibility such as pathways managent.
|
|
Tokenisers
|
|
The Pdoc lib provides the new level Pdoc::Tokeniser. It will feature modules used to extract low-level information. At present, the Perl.pm and Pod.pm modules are available for extracting respectively source code from Perl subroutines and POD content found under =headx tags. Each tokeniser returns a Pdoc::Document object with the tokens that can be used for conversion in another format (see Pdoc::Html::Tools::PerlHighLight for an example).
Note: with the addition of the tokenisers, many parser and converter modules have become obsolete such as PodItem, PodOver, PodBack, ...
|
|
Library configuration
|
|
Each converter module will transform the original data into a new format with default display parameters such as color, bold, italic, ... In order to be able to change these parameters, a Pdoc::Config.pm has been added. The Config module will be responsible to read/write the config parameters and will be used by any module to access config parameters. It is the driver script responsability to manage the Config object(s).
|
|
Experimental version
|
|
The experiment
|
|
The idea of Pdoc came after writing a large number of Perl modules and having no way to access the documentation quickly, easily and with 'nice' display. Since the Java documentation system is really good, something similar had to be done for Perl (and to get rid of these ugly pod2html pages). Being Perl and therefore having so many different programming styles, a single Perl script wouldn't be enough (my first attempt wasn't too bad until I tried on Bioperl - http://www.bioperl.org). As soon the Pdoc lib took shape, it has been used to document Ensembl code (http://www.ensembl.org) and from there it was obvious that a proper package should be out.
|
|
Documentation concept
|
|
The original objective was to transform Perl modules + embedded POD into HTML format. With the design of the library, the concept of the documentation procedure moved to a three step procedure consisting in 1) parsing a specific format into components 2) converting the components into a new format 3) generating a new document with the converted components arranged in a different layout. With such a procedure, Pdoc could be used to tranform any structured data into a new format without too much coding. The library should provide all the comodities to manipulate the data, the developer should add only small modules handling specific pieces of information.
|
|
Document concept
|
Without going for the complex stuff, a structured document can be parsed by retrieving bits and pieces and store these as entry objects into a document object. Each document entry has a name, a type, a content and a converted content. The document entry type will be used to characterise the type of data in the object, the name will be used to identify the entry from others of the same type. The content is generally text but could be a reference to any structured data.
See Pdoc::DocumentI, Pdoc::Document, Pdoc::DocEntryI and Pdoc::DocEntry in the Pdoc lib for more info.
|
|
Parsers
|
|
A generic parser module has been implemented to parse document objects (see the Pdoc::Parsers::Documents::ParserI interface), files (see the Pdoc::Parsers::Files::ParserI interface) and directory trees (see the Pdoc::Parsers::Trees::ParserI interface). The parser will extract the content from the input data and apply a number of parser modules on each fragment of data (i.e. each line for a file). The advantage being to extend the parsing capabilities just by adding new modules. Dedicated parsers can then be implemented to parse specific formats (just by combining the right parser modules). See Pdoc::Parsers::Files::PerlModule.
|
|
Conversion
|
|
Each piece of data extracted from a strucured document by a parser can be converted into a new format. Like for the parsing procedure, a generic converter module has been implemented to convert any Pdoc::Document object. Each component of the document should have a converter module matching its type. A converter dedicated to a specific type of format such as Pdoc::Html::Converters::PerlModule will use a number of converter modules related to Perl modules convertion to HTML format. The new format resulting from the convertion is stored with the document entry using the 'converted()' method.
|
|
Renderers
|
|
Once the document entries have been converted, the document can be rendered to its final form for publication. The renderer will layout the document entries in a structured way and will provide all the commodities to easily access these entries. The renderer will generally define the converter object required for the format transformation. See Pdoc::Html::Renderers::PerlModule.
|