The current method of adding multiple --insert or --verbatim parameters to the podwrapper command is not very easy to use because it involves modifying the Makefile.am in every place where this is used, plus under po-docs/$language/Makefile.am. It's better if the POD file itself can do the inclusion. This enhances support so that the special sequences __INCLUDE:file.pod__ or __VERBATIM:file.txt__ are treated as file inclusion. The filename must be a plain file and is searched along a path (supplied by the optional podwrapper --path parameter). The purpose of the path is to allow translations to happen more easily. For example we can include a particular POD fragment from common/options/ for the English version, but copy the translated file to po-docs/$language/ for every translated version. --- podwrapper.pl.in | 61 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/podwrapper.pl.in b/podwrapper.pl.in index 30b0ea7c2..f12a173f2 100755 --- a/podwrapper.pl.in +++ b/podwrapper.pl.in @@ -62,7 +62,28 @@ output options are I<--man>, I<--html> and I<--text> (see below). In C<Makefile.am> files, use a variation of the boilerplate shown in the L</SYNOPSIS> section above. -For information about the POD format, see L<perlpod(1)>. +=head1 POD FORMAT + +For general information about the POD format, see L<perlpod(1)>. + +podwrapper.pl has a couple of extensions for including files: + +=over 4 + +=item C<__INCLUDE:F<filename.pod>__> + +Include another POD file at the current position (this does not work +recursively). + +The filename is found by searching first the current directory, +then each I<--path> directory (if used). + +=item C<__VERBATIM:F<filename.txt>__> + +As above but the file is included as verbatim text, meaning it is +prefixed by one space before being passed to POD processing. + +=back =head1 OPTIONS @@ -135,6 +156,17 @@ of the input file. =cut +my @paths; + +=item B<--path DIR> + +Set the path used for searching for included files (see L</POD FORMAT> +above). The current directory is always searched first so you don’t +need to add that explicitly. Multiple I<--path> parameters can be +given, they are searched in order. + +=cut + my $section; =item B<--section N> @@ -221,6 +253,7 @@ GetOptions ("help|?" => \$help, "insert=s" => \@inserts, "man=s" => \$man, "name=s" => \$name, + "path=s" => \@paths, "section=s" => \$section, "strict-checks!" => \$strict_checks, "text=s" => \$text, @@ -314,6 +347,10 @@ foreach (@inserts) { if $content eq $oldcontent; } +# Perform INCLUDE directives. +$content =~ s{__INCLUDE:([-a-z0-9_]+\.pod)__} + {read_whole_file ("$1", use_path => 1)}ge; + # Turn external links to this man page into simple cross-section links. $content =~ s,\QL<$name($section)/\E,L</,g; @@ -328,6 +365,10 @@ foreach (@verbatims) { if $content eq $oldcontent; } +# Perform VERBATIM directives. +$content =~ s{__VERBATIM:([-a-z0-9_]+\.txt)__} + {read_verbatim_file ("$1", use_path => 1)}ge; + # There should be no =encoding line present in the content (we will add one). die "$progname: $input: =encoding must not be present in input\n" if $content =~ /^=encoding/m; @@ -642,11 +683,27 @@ if ($text) { #print "$progname: wrote $text\n"; } +sub find_file +{ + my $input = shift; + my $use_path = shift; + local $_; + + my @search_path = ("."); + push (@search_path, @paths) if $use_path; + foreach (@search_path) { + return "$_/$input" if -f "$_/$input"; + } + die "$progname: $input: cannot find input file on path" +} + sub read_whole_file { my $input = shift; + my %options = @_; local $/ = undef; + $input = find_file ($input, $options{use_path}); open FILE, $input or die "$progname: $input: $!"; $_ = <FILE>; close FILE; @@ -656,8 +713,10 @@ sub read_whole_file sub read_verbatim_file { my $input = shift; + my %options = @_; my $r = ""; + $input = find_file ($input, $options{use_path}); open FILE, $input or die "$progname: $input: $!"; while (<FILE>) { $r .= " $_"; -- 2.23.0

Use the common/options/key-option.pod fragment to document the --key option and selector instead of duplicating the same documentation everywhere. --- cat/Makefile.am | 4 ++++ cat/virt-cat.pod | 17 +---------------- cat/virt-log.pod | 17 +---------------- cat/virt-ls.pod | 17 +---------------- cat/virt-tail.pod | 17 +---------------- customize/Makefile.am | 1 + customize/virt-customize.pod | 17 +---------------- diff/Makefile.am | 1 + diff/virt-diff.pod | 17 +---------------- edit/Makefile.am | 1 + edit/virt-edit.pod | 17 +---------------- fish/Makefile.am | 2 +- fish/guestfish.pod | 17 +---------------- fuse/Makefile.am | 1 + fuse/guestmount.pod | 17 +---------------- get-kernel/Makefile.am | 1 + get-kernel/virt-get-kernel.pod | 17 +---------------- inspector/Makefile.am | 1 + inspector/virt-inspector.pod | 17 +---------------- po-docs/podfiles | 1 + sparsify/Makefile.am | 1 + sparsify/virt-sparsify.pod | 17 +---------------- sysprep/Makefile.am | 1 + sysprep/virt-sysprep.pod | 17 +---------------- 24 files changed, 27 insertions(+), 209 deletions(-) diff --git a/cat/Makefile.am b/cat/Makefile.am index 8e731d5b3..1d013e8dd 100644 --- a/cat/Makefile.am +++ b/cat/Makefile.am @@ -188,6 +188,7 @@ stamp-virt-cat.pod: virt-cat.pod $(PODWRAPPER) \ --man virt-cat.1 \ --html $(top_builddir)/website/virt-cat.1.html \ + --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning safe \ $< @@ -210,6 +211,7 @@ stamp-virt-log.pod: virt-log.pod $(PODWRAPPER) \ --man virt-log.1 \ --html $(top_builddir)/website/virt-log.1.html \ + --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning safe \ $< @@ -221,6 +223,7 @@ stamp-virt-ls.pod: virt-ls.pod $(PODWRAPPER) \ --man virt-ls.1 \ --html $(top_builddir)/website/virt-ls.1.html \ + --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning safe \ $< @@ -232,6 +235,7 @@ stamp-virt-tail.pod: virt-tail.pod $(PODWRAPPER) \ --man virt-tail.1 \ --html $(top_builddir)/website/virt-tail.1.html \ + --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning safe \ $< diff --git a/cat/virt-cat.pod b/cat/virt-cat.pod index 745d4a4b6..0c4ce4b77 100644 --- a/cat/virt-cat.pod +++ b/cat/virt-cat.pod @@ -121,22 +121,7 @@ If you have untrusted raw-format guest disk images, you should use this option to specify the disk format. This avoids a possible security problem with malicious guests (CVE-2010-3851). -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/cat/virt-log.pod b/cat/virt-log.pod index 8de000c5f..a6b37662e 100644 --- a/cat/virt-log.pod +++ b/cat/virt-log.pod @@ -105,22 +105,7 @@ If you have untrusted raw-format guest disk images, you should use this option to specify the disk format. This avoids a possible security problem with malicious guests (CVE-2010-3851). -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/cat/virt-ls.pod b/cat/virt-ls.pod index 8d6a9fe37..53141b2c6 100644 --- a/cat/virt-ls.pod +++ b/cat/virt-ls.pod @@ -352,22 +352,7 @@ Display file sizes in human-readable format. This option only has effect in I<-lR> output mode. See L</RECURSIVE LONG LISTING> above. -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/cat/virt-tail.pod b/cat/virt-tail.pod index cf8700d1a..9f72ce3f7 100644 --- a/cat/virt-tail.pod +++ b/cat/virt-tail.pod @@ -123,22 +123,7 @@ If you have untrusted raw-format guest disk images, you should use this option to specify the disk format. This avoids a possible security problem with malicious guests (CVE-2010-3851). -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/customize/Makefile.am b/customize/Makefile.am index a39308d26..5fae5226f 100644 --- a/customize/Makefile.am +++ b/customize/Makefile.am @@ -203,6 +203,7 @@ stamp-virt-customize.pod: virt-customize.pod $(top_srcdir)/common/mlcustomize/cu $(PODWRAPPER) \ --man virt-customize.1 \ --html $(top_builddir)/website/virt-customize.1.html \ + --path $(top_srcdir)/common/options \ --insert $(top_srcdir)/common/mlcustomize/customize-synopsis.pod:__CUSTOMIZE_SYNOPSIS__ \ --insert $(top_srcdir)/common/mlcustomize/customize-options.pod:__CUSTOMIZE_OPTIONS__ \ --license GPLv2+ \ diff --git a/customize/virt-customize.pod b/customize/virt-customize.pod index d1b568040..9182c2e6d 100644 --- a/customize/virt-customize.pod +++ b/customize/virt-customize.pod @@ -138,22 +138,7 @@ If you have untrusted raw-format guest disk images, you should use this option to specify the disk format. This avoids a possible security problem with malicious guests (CVE-2010-3851). -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/diff/Makefile.am b/diff/Makefile.am index 9452c6de2..2c82303dd 100644 --- a/diff/Makefile.am +++ b/diff/Makefile.am @@ -64,6 +64,7 @@ stamp-virt-diff.pod: virt-diff.pod $(PODWRAPPER) \ --man virt-diff.1 \ --html $(top_builddir)/website/virt-diff.1.html \ + --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning safe \ $< diff --git a/diff/virt-diff.pod b/diff/virt-diff.pod index 36ee10ced..0500598bd 100644 --- a/diff/virt-diff.pod +++ b/diff/virt-diff.pod @@ -166,22 +166,7 @@ security problem with malicious guests (CVE-2010-3851). Display file sizes in human-readable format. -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/edit/Makefile.am b/edit/Makefile.am index 5c90a93df..d1c2b5c48 100644 --- a/edit/Makefile.am +++ b/edit/Makefile.am @@ -62,6 +62,7 @@ stamp-virt-edit.pod: virt-edit.pod $(PODWRAPPER) \ --man virt-edit.1 \ --html $(top_builddir)/website/virt-edit.1.html \ + --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning general \ $< diff --git a/edit/virt-edit.pod b/edit/virt-edit.pod index 3cb3ce6da..4909a7df1 100644 --- a/edit/virt-edit.pod +++ b/edit/virt-edit.pod @@ -153,22 +153,7 @@ If you have untrusted raw-format guest disk images, you should use this option to specify the disk format. This avoids a possible security problem with malicious guests (CVE-2010-3851). -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/fish/Makefile.am b/fish/Makefile.am index dff56b2e2..ebff4b155 100644 --- a/fish/Makefile.am +++ b/fish/Makefile.am @@ -201,7 +201,7 @@ stamp-guestfish.pod: guestfish.pod guestfish-actions.pod guestfish-commands.pod $(PODWRAPPER) \ --man guestfish.1 \ --html $(top_builddir)/website/guestfish.1.html \ - --path $(srcdir) \ + --path $(srcdir) --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning ro-option \ $< diff --git a/fish/guestfish.pod b/fish/guestfish.pod index fd230c7bb..1904b640c 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -280,22 +280,7 @@ Using this flag is mostly equivalent to using the C<inspect-os> command and then using other commands to mount the filesystems that were found. -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/fuse/Makefile.am b/fuse/Makefile.am index e3b4a1cb5..826d11f09 100644 --- a/fuse/Makefile.am +++ b/fuse/Makefile.am @@ -101,6 +101,7 @@ stamp-guestmount.pod: guestmount.pod $(PODWRAPPER) \ --man guestmount.1 \ --html $(top_builddir)/website/guestmount.1.html \ + --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning ro-option \ $< diff --git a/fuse/guestmount.pod b/fuse/guestmount.pod index 9319d093c..d4e12e641 100644 --- a/fuse/guestmount.pod +++ b/fuse/guestmount.pod @@ -246,22 +246,7 @@ Using L<virt-inspector(1)> code, inspect the disks looking for an operating system and mount filesystems as they would be mounted on the real virtual machine. -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/get-kernel/Makefile.am b/get-kernel/Makefile.am index ef61c30e3..8692431e6 100644 --- a/get-kernel/Makefile.am +++ b/get-kernel/Makefile.am @@ -128,6 +128,7 @@ stamp-virt-get-kernel.pod: virt-get-kernel.pod $(PODWRAPPER) \ --man virt-get-kernel.1 \ --html $(top_builddir)/website/virt-get-kernel.1.html \ + --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning safe \ $< diff --git a/get-kernel/virt-get-kernel.pod b/get-kernel/virt-get-kernel.pod index 3802412e2..990d6a91f 100644 --- a/get-kernel/virt-get-kernel.pod +++ b/get-kernel/virt-get-kernel.pod @@ -89,22 +89,7 @@ If you have untrusted raw-format guest disk images, you should use this option to specify the disk format. This avoids a possible security problem with malicious guests (CVE-2010-3851). -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/inspector/Makefile.am b/inspector/Makefile.am index b6dc79027..c1d0a788b 100644 --- a/inspector/Makefile.am +++ b/inspector/Makefile.am @@ -82,6 +82,7 @@ stamp-virt-inspector.pod: virt-inspector.pod $(PODWRAPPER) \ --man virt-inspector.1 \ --html $(top_builddir)/website/virt-inspector.1.html \ + --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning safe \ $< diff --git a/inspector/virt-inspector.pod b/inspector/virt-inspector.pod index 98b278f26..24fbf2e08 100644 --- a/inspector/virt-inspector.pod +++ b/inspector/virt-inspector.pod @@ -114,22 +114,7 @@ parameter is ignored. If working with untrusted raw-format guest disk images, you should ensure the format is always specified. -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/po-docs/podfiles b/po-docs/podfiles index 43735135b..56da1fbc6 100644 --- a/po-docs/podfiles +++ b/po-docs/podfiles @@ -10,6 +10,7 @@ ../cat/virt-tail.pod ../common/mlcustomize/customize-options.pod ../common/mlcustomize/customize-synopsis.pod +../common/options/key-option.pod ../customize/virt-customize.pod ../daemon/guestfsd.pod ../df/virt-df.pod diff --git a/sparsify/Makefile.am b/sparsify/Makefile.am index a7cce7e38..bf1bb3e45 100644 --- a/sparsify/Makefile.am +++ b/sparsify/Makefile.am @@ -130,6 +130,7 @@ stamp-virt-sparsify.pod: virt-sparsify.pod $(PODWRAPPER) \ --man virt-sparsify.1 \ --html $(top_builddir)/website/virt-sparsify.1.html \ + --path $(top_srcdir)/common/options \ --license GPLv2+ \ --warning general \ $< diff --git a/sparsify/virt-sparsify.pod b/sparsify/virt-sparsify.pod index 3f5f9995f..93a9365ce 100644 --- a/sparsify/virt-sparsify.pod +++ b/sparsify/virt-sparsify.pod @@ -230,22 +230,7 @@ You can give this option multiple times. Do in-place sparsification instead of copying sparsification. See L</IN-PLACE SPARSIFICATION> below. -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> diff --git a/sysprep/Makefile.am b/sysprep/Makefile.am index 434645dee..ba0d22a60 100644 --- a/sysprep/Makefile.am +++ b/sysprep/Makefile.am @@ -192,6 +192,7 @@ stamp-virt-sysprep.pod: virt-sysprep.pod sysprep-extra-options.pod sysprep-opera --man virt-sysprep.1 \ --insert sysprep-extra-options.pod:__EXTRA_OPTIONS__ \ --insert sysprep-operations.pod:__OPERATIONS__ \ + --path $(top_srcdir)/common/options \ --html $(top_builddir)/website/virt-sysprep.1.html \ --license GPLv2+ \ --warning general \ diff --git a/sysprep/virt-sysprep.pod b/sysprep/virt-sysprep.pod index 8d248db94..6c0add241 100644 --- a/sysprep/virt-sysprep.pod +++ b/sysprep/virt-sysprep.pod @@ -186,22 +186,7 @@ If you have untrusted raw-format guest disk images, you should use this option to specify the disk format. This avoids a possible security problem with malicious guests (CVE-2010-3851). -=item B<--key> SELECTOR - -Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<SELECTOR> can be in one of the following formats: - -=over 4 - -=item B<--key> C<DEVICE>:key:KEY_STRING - -Use the specified C<KEY_STRING> as passphrase. - -=item B<--key> C<DEVICE>:file:FILENAME - -Read the passphrase from F<FILENAME>. - -=back +__INCLUDE:key-option.pod__ =item B<--keys-from-stdin> -- 2.23.0