Enable a few POD options:
- Don't generate an errata section in the output.
- Send errors and warnings to stderr.
- Die if any errors or warnings are seen while generating the outputs.
For every user command line tool (eg. guestfish or virt-cat) require
that the manual page has a DESCRIPTION section. This doesn't apply to
non-CLI man pages (eg. guestfs-perl, guestfs-faq).
Move the random set of HTML files we build from html/ into
the website/ directory.
Also in the website/ directory, put the index.html file from
http://libguestfs.org, which was previously not under version control.
It is generated from index.html.in so we can automatically add the
current version and release date.
Also in the website/ directory, put various CSS file, images, etc.
which are required by the website and were also previously not under
version control.
Change the 'make website' rule to 'make maintainer-upload-website'.
As the name suggests, it is only useful for the maintainer, and will
fail with an error for anyone else.
Instead of hardcoding the location of perl (assuming it is installed in
/usr), use /usr/bin/env to run it, and thus picking it from $PATH.
This makes it possible to run these scripts also on installations with
perl in a different prefix than /usr.
Also, given that we want enable warnings on scripts, turn the -w
previously in shebang to explicit "use warnings;" in scripts which
didn't have it before.
When convering a POD documentation, possibily combining various
sub-documents together, simplify the L<> links that explicitly point to
the very same documentation being generated.
For example, when generating the virt-builder documentation, links like
L<virt-builder(1)/SECTION>
will be turned into
L</SECTION>
thus not making Pod::Simple parse them as external reference.
While it is a slightly crude hack, it seems there's no easy way to
process the link parsing with Pod::Simple subclasses.
Commit c4dc70f8c4 broke the man pages
for the Perl scripts in the tools/ directory.
It inserted the =encoding line at the top of the file, instead of in
front of the first =head1 entry, and this meant that the #!/usr/bin/perl
and the prologue became a part of the POD, which was not intended.
This changes podwrapper so that the input (POD) files should not
contain an =encoding directive. However they must be UTF-8.
Podwrapper then adds the '=encoding utf8' directive back during final
generation.
This in particular avoids problems with nested =encoding directives in
fragments. These break POD, and are undesirable anyway.
These don't contain literal strings like "AUTHORS" (they have the
translated versions instead) and so checking for these English strings
is rather useless.
Also we don't usually have the '--license' parameter conveniently
around so don't enforce this section.
This adds standard LICENSE and BUGS sections to all of the man pages
that are processed by podwrapper.
Modify all the calls to $(PODWRAPPER) to add the right --license
parameter according to the content. Note that this relaxes the
license on some code example pages, making them effectively BSD-style
licensed.
This uses Pod::Simple so it properly parses the input POD and can
generate proper custom output as required specifically by libguestfs.
One immediate benefit is that links between and within manual pages
now work mostly correctly.
