NAME
   DocSet - documentation projects builder in HTML, PS and PDF formats

SYNOPSIS
     docset_build [options] base_full_path relative_to_base_config_file_location

   Options:

     -h    this help
     -v    verbose
     -i    podify pseudo-pod items (s/^* /=item */)
     -s    create the splitted html version (not implemented)
     -t    create tar.gz (not implemented)
     -p    generate PS file
     -d    generate PDF file
     -f    force a complete rebuild
     -a    print available hypertext anchors (not implemented)
     -l    perform L<> links validation in pod docs
     -e    slides mode (for presentations) (not implemented)
     -m    executed from Makefile (forces rebuild,
                                   no PS/PDF file,
                                   no tgz archive!)

DESCRIPTION
   This package builds a docset from sources in different formats. The
   generated documents can be all nicely interlinked and to have the same
   look and feel.

   Currently it knows to handle input formats:

   * POD * HTML

   and knows to generate:

   * HTML * PS * PDF

 Modification control
   Each output mode maintains its own cache (per docset) which is used when
   certain source documents weren't modified since last build and the build
   is running in a non-force-rebuild mode.

 Definitions:
   * Chapter is a single document (file).

   * Link is an URL

   * Docset is a collection of docsets, chapters and links.

 Application Specific Features
   1   META: not ported yet!

       Generate a split version HTML, creating html file for each pod
       section, and having everything interlinked of course. This version
       is used best for the search.

   1   Complete the POD on the fly from the files in POD format. This is
       used to ease the generating of the presentations slides, so one can
       use "*" instead of a long =over/=item/.../=item/=back strings. The
       rest is done as before. Take a look at the special version of the
       html2ps format to generate nice slides in
       *conf/html2ps-slides.conf*.

   1   If you turn the slides mode on, it automatically turns the "-i" ("*"
       bullets preprocessing) mode and does a page break before each =head
       tag.

 Examples
   The package includes two fully working examples in the *examples/*
   directory.

   site
       This example demonstrates a shrinked version of perl.apache.org
       (which is genrated entirely by DocSet), with many docs removed or
       reduced to the mininumum. There are still quite a lot of documents
       left so you can see the big picture. Read *examples/site/README* for
       more information.

   presentation
       This example demonstrates how to build presentations handouts and
       slides using DocSet. Read *examples/presentation/README* for more
       information.

 Look-n-Feel Customization
   You can customise the look and feel of the ouput by adjusting the
   templates in the directory *examples/site/tmpl/custom*.

   You can change look and feel of the PS (PDF) versions by modifying
   *examples/site/conf/html2ps.conf*. Be careful that if your documentation
   that you want to put in one PS or PDF file is very big and you tell
   html2ps to put the TOC at the beginning you will need lots of memory
   because it won't write a single byte to the disk before it gets all the
   HTML markup converted to PS.

CONFIGURATION
   All you have to prepare is a single config file that you then pass as an
   argument to "docset_build":

     % docset_build [options] base_full_path relative_to_base_config_file_location

   Every directory in the source tree may have a configuration file, which
   designates a docset's root. See the *config* files for examples. Usually
   the file in the root (*examples/site/src*) sets operational directories
   and other arguments, which you don't have to repeat in sub-docsets. You
   want to redefine the build attributes in nested docsets if you want to
   override certain configuration attributes. Modify these files to suit
   your documentation project layout.

   Note that the smart *examples/site/bin/build* script automatically
   locates your project's directory, so you can move your project around
   filesystem without changing anything. So you really build with:

     % bin/build [options]

   *examples/site/README* explains the layout of the directories.

   "DocSet::Config" manpage explains the layout of the configuration file.

Extending
   Read the other manpages for more information about how to extend Docset.

PREREQUISITES
   The following are the optional prerequisites:

   * ps2pdf
       Needed to generate the PDF version.

   * Storable
       Available from CPAN (http://cpan.org/) and is a part of the core
       Perl distribution of the Perl 5.8.0 and higher.

       Allows source modification control, so if you modify only one file
       you will not have to rebuild everything to get the updated
       HTML/PS/PDF files.

SUPPORT
   Notice that this tool relies on two tools ("ps2pdf" and "html2ps") which
   I don't support, since I didn't write them. So if you have any problem
   first make sure that it's not a problem of these tools.

   Note that while "html2ps" is included in this distribution, it's written
   in the old style Perl, so if you have patches send them along, but I
   won't try to fix/modify this code otherwise. For more info see:
   http://www.tdb.uu.se/~jan/html2ps.html

BUGS
   Huh? Probably many...

QUESTIONS
   Questions can be asked at the template-docset mailing list. For mailing
   list archives and subscription information please see:
   http://template-toolkit.org/mailman/listinfo/template-docset

AUTHORS
   Stas Bekman <stas (at) stason.org>

SEE ALSO
   perl(1), Pod::POM(3), Pod::HTML(3), html2ps(1), ps2pod(1), Storable(3)

COPYRIGHT
   This program is distributed under the Artistic License, like the Perl
   itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.