thr3ads.net - Libguestfs - [Libguestfs] [PATCH libguestfs 1/3] podwrapper: __INCLUDE:file.pod__ and __VERBATIM:file.txt_

If this information is useful, please help other people find it:
Share via:

Richard W.M. Jones

2019-Nov-26 18:13 UTC

[Libguestfs] [PATCH libguestfs 0/3] options: Describe --key SELECTOR in a single file.

The libguestfs part of this change.
Also a virt-v2v part will be needed.

The first patch adds a new feature to podwrapper so that we can use
__INCLUDE:file__ directives within the POD itself (instead of using
--insert, and one day replacing that).

The second patch shows how this change could be used for the included
parts of the guestfish man page, including the non-English pages under
po-docs/$language.

The third patch unifies the --key SELECTOR documentation using this
mechanism.  Note this also unifies the translated documentation too,
although because of the way it works no actual changes are needed to
po-docs/

Rich.

Richard W.M. Jones

2019-Nov-26 18:13 UTC

head link

[Libguestfs] [PATCH libguestfs 1/3] podwrapper: INCLUDE:file.pod and VERBATIM:file.txt in POD files.

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 | 62 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/podwrapper.pl.in b/podwrapper.pl.in
index 30b0ea7c2..2b1f0caa4 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 directory in the I<--path> parameter (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,16 @@ of the input file.
 
 =cut
 
+my $path;
+
+=item B<--path DIR[: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.
+
+=cut
+
 my $section;
 
 =item B<--section N>
@@ -221,6 +252,7 @@ GetOptions ("help|?" => \$help,
             "insert=s" => \@inserts,
             "man=s" => \$man,
             "name=s" => \$name,
+            "path=s" => \$path,
             "section=s" => \$section,
             "strict-checks!" => \$strict_checks,
             "text=s" => \$text,
@@ -314,6 +346,10 @@ foreach (@inserts) {
         if $content eq $oldcontent;
 }
 
+# Perform INCLUDE directives.
+$content =~ s{__INCLUDE:([-a-z0-9_]+\.pod)__}
+             {read_whole_file ("$1", path => $path)}ge;
+
 # Turn external links to this man page into simple cross-section links.
 $content =~ s,\QL<$name($section)/\E,L</,g;
 
@@ -328,6 +364,10 @@ foreach (@verbatims) {
         if $content eq $oldcontent;
 }
 
+# Perform VERBATIM directives.
+$content =~ s{__VERBATIM:([-a-z0-9_]+\.txt)__}
+             {read_verbatim_file ("$1", path => $path)}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 +682,29 @@ if ($text) {
     #print "$progname: wrote $text\n";
 }
 
+sub find_file
+{
+    my $input = shift;
+    my $path = shift;
+    local $_;
+
+    my @path = (".");
+    if ($path) {
+        push (@path, split (/:/, $path))
+    }
+    foreach (@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{path});
     open FILE, $input or die "$progname: $input: $!";
     $_ = <FILE>;
     close FILE;
@@ -656,8 +714,10 @@ sub read_whole_file
 sub read_verbatim_file
 {
     my $input = shift;
+    my %options = @_;
     my $r = "";
 
+    $input = find_file ($input, $options{path});
     open FILE, $input or die "$progname: $input: $!";
     while (<FILE>) {
         $r .= " $_";
-- 
2.23.0

Richard W.M. Jones

2019-Nov-26 18:13 UTC

head link

[Libguestfs] [PATCH libguestfs 2/3] fish: Update documentation to use new INSERT:..._ directive.

---
 fish/Makefile.am    | 4 +---
 fish/guestfish.pod  | 6 +++---
 po-docs/language.mk | 3 ---
 3 files changed, 4 insertions(+), 9 deletions(-)

diff --git a/fish/Makefile.am b/fish/Makefile.am
index 0e01ed9fd..dff56b2e2 100644
--- a/fish/Makefile.am
+++ b/fish/Makefile.am
@@ -201,9 +201,7 @@ stamp-guestfish.pod: guestfish.pod guestfish-actions.pod
guestfish-commands.pod
 	$(PODWRAPPER) \
 	  --man guestfish.1 \
 	  --html $(top_builddir)/website/guestfish.1.html \
-	  --insert $(srcdir)/guestfish-actions.pod:__ACTIONS__ \
-	  --insert $(srcdir)/guestfish-commands.pod:__FISH_COMMANDS__ \
-	  --insert $(srcdir)/guestfish-prepopts.pod:__PREPOPTS__ \
+	  --path $(srcdir) \
 	  --license GPLv2+ \
 	  --warning ro-option \
 	  $<
diff --git a/fish/guestfish.pod b/fish/guestfish.pod
index 06644c5b8..fd230c7bb 100644
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -1133,7 +1133,7 @@ F<test1.img>):
 
  guestfish -N blankdisk.img=disk:200M
 
-__PREPOPTS__
+__INCLUDE:guestfish-prepopts.pod__
 
 =head1 ADDING REMOTE STORAGE
 
@@ -1403,11 +1403,11 @@ With I<-l> or I<--list>, this list all
commands.
 
 This exits guestfish.  You can also use C<^D> key.
 
-__FISH_COMMANDS__
+__INCLUDE:guestfish-commands.pod__
 
 =head1 COMMANDS
 
-__ACTIONS__
+__INCLUDE:guestfish-actions.pod__
 
 =head1 EXIT STATUS
 
diff --git a/po-docs/language.mk b/po-docs/language.mk
index b7d574db3..108cf8c4c 100644
--- a/po-docs/language.mk
+++ b/po-docs/language.mk
@@ -131,9 +131,6 @@ guestfish.1: guestfish.pod guestfish-actions.pod
guestfish-commands.pod guestfis
 	  --no-strict-checks \
 	  --man $@ \
 	  --license GPLv2+ \
-	  --insert $(srcdir)/guestfish-actions.pod:__ACTIONS__ \
-	  --insert $(srcdir)/guestfish-commands.pod:__FISH_COMMANDS__ \
-	  --insert $(srcdir)/guestfish-prepopts.pod:__PREPOPTS__ \
 	  $<
 
 virt-builder.1: virt-builder.pod customize-synopsis.pod customize-options.pod
-- 
2.23.0

Richard W.M. Jones

2019-Nov-26 18:13 UTC

head link

[Libguestfs] [PATCH libguestfs 3/3] options: Update documentation for --key SELECTOR.

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..932c66398 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):$(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

Pino Toscano

2019-Nov-27 12:27 UTC

head link

Re: [Libguestfs] [PATCH libguestfs 1/3] podwrapper: INCLUDE:file.pod and VERBATIM:file.txt in POD files.

On Tuesday, 26 November 2019 19:13:21 CET Richard W.M. Jones
wrote:> +my $path;
> +
> +=item B<--path DIR[: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.
I believe we can improve the handling of this option, for example
allowing multiple occurrences.
> @@ -642,11 +682,29 @@ if ($text) {
>      #print "$progname: wrote $text\n";
>  }
>  
> +sub find_file
> +{
> +    my $input = shift;
> +    my $path = shift;
> +    local $_;
> +
> +    my @path = (".");
> +    if ($path) {
> +        push (@path, split (/:/, $path))
> +    }
This splits the include path every time, while the list of paths does
not change.  Most probably we can do the following:

   my @paths = ('.');
   [...]
   GetOptions(
       "path=s" => sub {
            push @paths, split(/:/, $_[1]);
       },
   [...]

This way:
- @paths is already there as array
- @paths already includes '.' as first element
- --path can still be a colon-separated list of paths
- --path can be specified multiple times

BTW is the colon-separated value for --path needed? Reading the other
two patches of this series, I see the values are only a single
directory every time. In this case, the proposal above can be
simplified as:

   my @paths = ('.');
   [...]
   GetOptions(
       "path=s" => \@paths,
   [...]

-- 
Pino Toscano

Maybe Matching Threads

Search for more possibly parallel threads

Libguestfs - Nov 2019 - [PATCH libguestfs 1/3] podwrapper: __INCLUDE:file.pod__ and __VERBATIM:file.txt__ in POD files.

[Libguestfs] [PATCH libguestfs 0/3] options: Describe --key SELECTOR in a single file.

[Libguestfs] [PATCH libguestfs 1/3] podwrapper: __INCLUDE:file.pod__ and __VERBATIM:file.txt__ in POD files.

[Libguestfs] [PATCH libguestfs 2/3] fish: Update documentation to use new __INSERT:...___ directive.

[Libguestfs] [PATCH libguestfs 3/3] options: Update documentation for --key SELECTOR.

Re: [Libguestfs] [PATCH libguestfs 1/3] podwrapper: __INCLUDE:file.pod__ and __VERBATIM:file.txt__ in POD files.

Maybe Matching Threads

Libguestfs - Nov 2019 - [PATCH libguestfs 1/3] podwrapper: INCLUDE:file.pod and VERBATIM:file.txt in POD files.

[Libguestfs] [PATCH libguestfs 1/3] podwrapper: INCLUDE:file.pod and VERBATIM:file.txt in POD files.

[Libguestfs] [PATCH libguestfs 2/3] fish: Update documentation to use new INSERT:..._ directive.

Re: [Libguestfs] [PATCH libguestfs 1/3] podwrapper: INCLUDE:file.pod and VERBATIM:file.txt in POD files.