From 9586488a34d5d99f7d98b597d4d5aeda61943c1d Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Thu, 10 Jan 2013 06:25:30 +0900 Subject: [PATCH 7/7] podwrapper: Refresh podwrapper man page. This also adds a rule so you can do: make podwrapper.1 if you want to read the documentation as a man page. --- .gitignore | 1 + Makefile.am | 11 ++++++++++ podwrapper.pl.in | 63 ++++++++++++++++++++++++++++++++++++-------------------- 3 files changed, 53 insertions(+), 22 deletions(-) diff --git a/.gitignore b/.gitignore index 7f8c892..394e20a 100644 --- a/.gitignore +++ b/.gitignore @@ -320,6 +320,7 @@ Makefile.in /po-docs/po4a.conf /po-docs/*/*.pod /po-docs/*/stamp-update-po +/podwrapper.1 /podwrapper.pl /po/*.gmo /python/bindtests.py diff --git a/Makefile.am b/Makefile.am index d8b6590..42052c0 100644 --- a/Makefile.am +++ b/Makefile.am @@ -288,11 +288,22 @@ stamp-guestfs-release-notes.pod: guestfs-release-notes.pod $< touch $@ +# NB. podwrapper is an internal tool, so the man page mustn't be installed. +noinst_MANS = podwrapper.1 +podwrapper.1: podwrapper.pl + $(PODWRAPPER) \ + --section 1 \ + --man $@-t \ + --license GPLv2+ \ + $< + mv $@-t $@ + # Make clean. CLEANFILES = \ html/*.html \ pod2htm?.tmp \ + podwrapper.1 \ qemu-wrapper.sh \ stamp-guestfs-release-notes.pod diff --git a/podwrapper.pl.in b/podwrapper.pl.in index 46c71f2..3998782 100755 --- a/podwrapper.pl.in +++ b/podwrapper.pl.in @@ -32,27 +32,37 @@ use File::Basename; =head1 NAME -podwrapper.pl - Generate various output formats from POD input files +podwrapper.pl - Generate libguestfs documentation from POD input files =head1 SYNOPSIS + man_MANS = virt-foo.1 + virt-foo.1 $(top_builddir)/html/virt-foo.1.html: stamp-virt-foo.pod + stamp-virt-foo.pod: virt-foo.pod - $(PODWRAPPER) --man virt-foo.1 --html virt-foo.1.html $< - touch $@ + $(PODWRAPPER) \ + --section 1 \ + --man virt-foo.1 \ + --html $(top_builddir)/html/virt-foo.1.html \ + --license GPLv2+ \ + $< + touch $@ + + CLEANFILES += stamp-virt-foo.pod =head1 DESCRIPTION -podwrapper is a Perl script that generates various output formats +podwrapper.pl is a Perl script that generates various output formats from POD input files that libguestfs uses for most documentation. -You should specify an input file, and one or more output formats. -For example: +You must specify one input file, and one or more output formats. The +output options are I<--man>, I<--html> and I<--text> (see below). - podwrapper.pl virt-foo.pod --man virt-foo.1 +In C files, use a variation of the boilerplate shown in +the L section above. -will turn C into a man page C. The output -options are I<--man>, I<--html> and I<--text> (see below). +For information about the POD format, see L. =head1 OPTIONS @@ -70,7 +80,7 @@ Display brief help. my $html; -=item B<--html=output.html> +=item B<--html output.html> Write a web page to C. If this option is not given, then no web page output is produced. @@ -79,7 +89,7 @@ given, then no web page output is produced. my @inserts; -=item B<--insert=filename:__PATTERN__> +=item B<--insert filename:__PATTERN__> In the input file, replace the literal text C<__PATTERN__> with the replacement file C. You can give this option multiple @@ -95,7 +105,11 @@ patterns, in fact you can use any string as the pattern. my @licenses; -=item B<--license=GPLv2+|LGPLv2+|examples> +=item B<--license GPLv2+> + +=item B<--license LGPLv2+> + +=item B<--license examples> Add the given license to the end of the man page. This parameter is required. The parameter may be given multiple times (eg. for @@ -105,16 +119,16 @@ mixed content). my $man; -=item B<--man=output.n> +=item B<--man output.n> -Write a man page to C. If this option is not -given, then no man page output is produced. +Write a man page to C (C is the manual section number). +If this option is not given, then no man page output is produced. =cut my $name; -=item B<--name=name> +=item B<--name name> Set the name of the man page. If not set, defaults to the basename of the input file. @@ -123,7 +137,7 @@ of the input file. my $section; -=item B<--section=N> +=item B<--section N> Set the section of the man page (a number such as C<1> for command line utilities or C<3> for C API documentation). If @@ -143,7 +157,7 @@ subdirectory. my $text; -=item B<--text=output.txt> +=item B<--text output.txt> Write a text file to C. If this option is not given, then no text output is produced. @@ -152,7 +166,7 @@ given, then no text output is produced. my @verbatims; -=item B<--verbatim=filename:@PATTERN@> +=item B<--verbatim filename:__PATTERN__> In the input file, replace the literal text C<__PATTERN__> with the replacement file C. You can give this option multiple @@ -529,11 +543,16 @@ sub read_verbatim_file $r; } +=head1 SEE ALSO + +L, +L, +libguestfs.git/README. + =head1 AUTHOR Richard W.M. Jones. -=head1 SEE ALSO +=head1 COPYRIGHT -libguestfs.git/README, -L +Copyright (C) 2012-2013 Red Hat Inc. -- 1.7.11.7