1
package Pod::HtmlPsPdf;
7
Pod::HtmlPsPdf - documentation projects builder in HTML, PS and PDF formats
11
pod2hpp [options] configuration_file_location
17
-i podify pseudo-pod items (s/^* /=item */)
18
-s create the splitted html version
22
-f force a complete rebuild
23
-a print available hypertext anchors
24
-l do hypertext links validation
25
-e slides mode (for presentations)
26
-m executed from Makefile (forces rebuild,
32
This code knows to do following with a collection of your POD files.
42
Generate a split version HTML, creating html file for each pod
43
section, and having everything interlinked of course. This version is
44
used best for the search.
48
Generate a single book-like version in PostScript format
52
Generate a single book-like version in PDF format
56
Complete the POD on the fly from the files in POD format. This is used
57
to ease the generating of the presentations slides, so one can use
58
C<*> instead of a long =over/=item/.../=item/=back strings. The rest
59
is done as before. Take a look at the special version of the html2ps
60
format to generate nice slides in I<conf/html2ps-slides.conf>.
64
If you turn the slides mode on, it automatically turns the C<-i> (C<*>
65
preprocessing) mode and does a page break before each =head tag.
69
You can customise the look and feel of the HTML files, PS and
70
therefore the PDF by tweaking the template files in I<./tmpl>
73
You can change look and feel of the PS (PDF) versions by modifying
74
I<./conf/html2ps.conf>. Be careful that if your documentation that
75
you want to put in one PS or PDF file is very big and you tell html2ps
76
to put the TOC at the beginning you will need lots of memory because
77
it won't write a single byte to the disk before it gets all the HTML
78
markup converted to PS.
80
To generate HTML this code use a slightly modified version of the
81
C<Pod::Html> code and than does a lot of massage on the resulting
82
HTML. I've tried to keep the pod2html code modified as little as
83
possible, so when a new versions of the original C<Pod::Html> module
84
will be released I'll be able to merge the changes with my version.
86
=head1 EXTENDED POD SYNTAX
88
I've extended the POD syntax to accomodate my own needs. Note that
89
this can be always converted back to the standard POD. To see the
90
extended syntax, refer to the I<docs/extended_pod.pod> in the package
96
All you have to prepare is a single config file that you then pass as
97
an argument to C<pod2hpp>:
99
pod2hpp [options] /full/path/to/config/file
101
Use the file I<project.config> supplied in the directory
102
I<sample>. Modify it to be suit your documentation project layout.
104
Note that I<sample/bin/build> script automatically locates your
105
project's directory, so you can move your project around filesystem
106
without changing anything.
108
I<sample/README.sample> explains the layout of the directories. The
109
easiest way to learn to use this package is to look at the
110
C<Apache::mod_perl_guide> package available at CPAN. I've developed
111
the package C<Pod::HtmlPsPdf> especially for
112
C<Apache::mod_perl_guide>.
116
All these are not required if all you want is to generate only the
123
Needed to generate the PDF version
127
Perl module available from CPAN (http://cpan.org/)
129
Allows source modification control, so if you modify only one file you
130
will not have to rebuild everything to get the updated HTML/PS/PDF
138
Notice that this tool relies on two tools (ps2pdf and html2ps) which I
139
don't support. So if you have any problem first make sure that it's
140
not a problem of these tools.
142
Note that while C<html2ps> is included in this distribution, it's
143
written in the old style Perl, so if you have patches send them along,
144
but I won't try to fix/modify this code otherwise. I didn't write this
147
This package works for me on Linux RedHat and Mandrake systems. I
148
release it only to share. Unfortunately I don't have time to help with
149
each available platform. If you have a problem, please don't contact
150
me. I'm not going to solve it. If you solve the problem, I'll gladly
151
accept the patch for others to benefit. Remember that this is a free
156
Huh? Probably many...
160
Stas Bekman <stas@stason.org>
164
perl(1), Pod::HTML(3), html2ps(1), ps2pod(1), Storable(3)
168
This program is distributed under the Artistic License, like the Perl