doc/Pod/HtmlPsPdf.pm

package Pod::HtmlPsPdf;

$VERSION = '0.03';

=head1 NAME

Pod::HtmlPsPdf - documentation projects builder in HTML, PS and PDF formats

=head1 SYNOPSIS

  pod2hpp [options] configuration_file_location

Options:

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

=head1 DESCRIPTION

This code knows to do following with a collection of your POD files.

=over

=item 1

Generate HTMLs

=item 2

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.

=item 3

Generate a single book-like version in PostScript format

=item 4

Generate a single book-like version in PDF format

=item 5

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
C<*> 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 I<conf/html2ps-slides.conf>.

=item 6 

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

=back

You can customise the look and feel of the HTML files, PS and
therefore the PDF by tweaking the template files in I<./tmpl>
directory.

You can change look and feel of the PS (PDF) versions by modifying
I<./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.

To generate HTML this code use a slightly modified version of the
C<Pod::Html> code and than does a lot of massage on the resulting
HTML. I've tried to keep the pod2html code modified as little as
possible, so when a new versions of the original C<Pod::Html> module
will be released I'll be able to merge the changes with my version.

=head1 EXTENDED POD SYNTAX

I've extended the POD syntax to accomodate my own needs. Note that
this can be always converted back to the standard POD. To see the
extended syntax, refer to the I<docs/extended_pod.pod> in the package
distribution.


=head1 CONFIGURATION

All you have to prepare is a single config file that you then pass as
an argument to C<pod2hpp>:

  pod2hpp [options] /full/path/to/config/file

Use the file I<project.config> supplied in the directory
I<sample>. Modify it to be suit your documentation project layout.

Note that I<sample/bin/build> script automatically locates your
project's directory, so you can move your project around filesystem
without changing anything.

I<sample/README.sample> explains the layout of the directories. The
easiest way to learn to use this package is to look at the
C<Apache::mod_perl_guide> package available at CPAN. I've developed
the package C<Pod::HtmlPsPdf> especially for
C<Apache::mod_perl_guide>.

=head1 PREREQUISITES

All these are not required if all you want is to generate only the
html version.

=over 4

=item * ps2pdf

Needed to generate the PDF version

=item * Storable

Perl module available from CPAN (http://cpan.org/)

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.

=back


=head1 SUPPORT

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

Note that while C<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. I didn't write this
utility.

This package works for me on Linux RedHat and Mandrake systems. I
release it only to share. Unfortunately I don't have time to help with
each available platform.  If you have a problem, please don't contact
me. I'm not going to solve it. If you solve the problem, I'll gladly
accept the patch for others to benefit. Remember that this is a free
software.

=head1 BUGS

Huh? Probably many...

=head1 AUTHOR

Stas Bekman <stas@stason.org>

=head1 SEE ALSO

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

=head1 COPYRIGHT

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

=cut
1	adcroft	1.1	package Pod::HtmlPsPdf;
2
3			$VERSION = '0.03';
4
5			=head1 NAME
6
7			Pod::HtmlPsPdf - documentation projects builder in HTML, PS and PDF formats
8
9			=head1 SYNOPSIS
10
11			pod2hpp [options] configuration_file_location
12
13			Options:
14
15			-h this help
16			-v verbose
17			-i podify pseudo-pod items (s/^* /=item */)
18			-s create the splitted html version
19			-t create tar.gz
20			-p generate PS file
21			-d generate PDF file
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,
27			no PS/PDF file,
28			no tgz archive!)
29
30			=head1 DESCRIPTION
31
32			This code knows to do following with a collection of your POD files.
33
34			=over
35
36			=item 1
37
38			Generate HTMLs
39
40			=item 2
41
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.
45
46			=item 3
47
48			Generate a single book-like version in PostScript format
49
50			=item 4
51
52			Generate a single book-like version in PDF format
53
54			=item 5
55
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>.
61
62			=item 6
63
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.
66
67			=back
68
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>
71			directory.
72
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.
79
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.
85
86			=head1 EXTENDED POD SYNTAX
87
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
91			distribution.
92
93
94			=head1 CONFIGURATION
95
96			All you have to prepare is a single config file that you then pass as
97			an argument to C<pod2hpp>:
98
99			pod2hpp [options] /full/path/to/config/file
100
101			Use the file I<project.config> supplied in the directory
102			I<sample>. Modify it to be suit your documentation project layout.
103
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.
107
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>.
113
114			=head1 PREREQUISITES
115
116			All these are not required if all you want is to generate only the
117			html version.
118
119			=over 4
120
121			=item * ps2pdf
122
123			Needed to generate the PDF version
124
125			=item * Storable
126
127			Perl module available from CPAN (http://cpan.org/)
128
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
131			files.
132
133			=back
134
135
136			=head1 SUPPORT
137
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.
141
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
145			utility.
146
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
152			software.
153
154			=head1 BUGS
155
156			Huh? Probably many...
157
158			=head1 AUTHOR
159
160			Stas Bekman <stas@stason.org>
161
162			=head1 SEE ALSO
163
164			perl(1), Pod::HTML(3), html2ps(1), ps2pod(1), Storable(3)
165
166			=head1 COPYRIGHT
167
168			This program is distributed under the Artistic License, like the Perl
169			itself.
170
171			=cut