9:18 a.m.
---
podwrapper.pl.in | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 73 insertions(+), 2 deletions(-)
diff --git a/podwrapper.pl.in b/podwrapper.pl.in
index 37e3e84..fd7a502 100755
--- a/podwrapper.pl.in
+++ b/podwrapper.pl.in
@@ -47,6 +47,7 @@ podwrapper.pl - Generate libguestfs documentation from POD input files
--man virt-foo.1 \
--html $(top_builddir)/website/virt-foo.1.html \
--license GPLv2+ \
+ --warning general \
$<
touch $@
@@ -182,6 +183,31 @@ patterns, in fact you can use any string as the pattern.
=cut
+my $warning = "not-set";
+
+=item B<--warning general>
+
+=item B<--warning ro-option>
+
+Add a standard warning section near the top of the manual page,
+warning the user not to use the tool in write mode or concurrently.
+
+There are two variations of the warning: The I<--warning ro-option>
+variation should be used with tools such as L<guestfish(1)> which have
+an I<--ro> option. The I<--warning general> variation should be used
+with other tools that open the disk image for writes, with no
+read-only option.
+
+=item B<--warning custom>
+
+Use I<--warning custom> if there is already a warning section in the
+manual page.
+
+=item B<--warning safe>
+
+Use I<--warning safe> for tools which are safe, ie. only open disk
+images in read-only mode, or just don't need a warning section.
+
=back
=cut
@@ -200,7 +226,8 @@ GetOptions ("help|?" => \$help,
"section=s" => \$section,
"strict-checks!" => \$strict_checks,
"text=s" => \$text,
- "verbatim=s" => \@verbatims
+ "verbatim=s" => \@verbatims,
+ "warning=s" => \$warning,
) or pod2usage (2);
pod2usage (1) if $help;
@@ -221,6 +248,13 @@ $section = 1 unless defined $section;
# Is it a user command line tool?
my $cli_tool = $section == 1 && $name !~ /^guestfs-/;
+# Warning parameter is mandatory for user tools in section 1.
+if ($strict_checks && $cli_tool) {
+ die "$progname: $input: missing argument: --warning parameter is missing or
invalid\n"
+ unless $warning eq "general" || $warning eq "ro-option" ||
+ $warning eq "custom" || $warning eq "safe";
+}
+
# Note that these @...@ are substituted by ./configure.
my $abs_top_srcdir = "@abs_top_srcdir@";
my $abs_top_builddir = "@abs_top_builddir@";
@@ -266,6 +300,7 @@ my $release = "$package_name-$package_version";
#print "name=$name\n";
#print "section=$section\n";
#print "date=$date\n";
+#print "warning=$warning\n";
# Read the input.
my $content = read_whole_file ($input);
@@ -318,9 +353,18 @@ if ($strict_checks) {
die "$progname: $input: GPL/LGPL should be specified using the --license
parameter, not included in the POD file\n"
if $content =~ /^This program is free software/ ||
$content =~ /^This library is free software/;
+ if ($warning eq "general" || $warning eq "ro-option" ||
+ $warning eq "safe") {
+ die "$progname: $input: WARNING is now added automatically using the
--warning parameter\n"
+ if $content =~ /^=head1 WARNING/m
+ }
+ elsif ($warning eq "custom") {
+ die "$progname: $input: missing WARNING section\n"
+ unless $content =~ /^=head1 WARNING/m;
+ }
}
-# Add standard LICENSE and BUGS sections.
+# Add standard LICENSE, BUGS and WARNING sections.
my $LGPLv2plus =
"This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published
@@ -393,6 +437,25 @@ output into the bug report.
\=back
";
+my $warning_general =
+"Using C<$name>
+on live virtual machines, or concurrently with other
+disk editing tools, can be dangerous, potentially causing disk
+corruption. The virtual machine must be shut down before you use this
+command, and disk images must not be edited concurrently.";
+
+my $warning_ro_option =
+"Using C<$name> in write mode
+on live virtual machines, or concurrently with other
+disk editing tools, can be dangerous, potentially causing disk
+corruption. The virtual machine must be shut down before you use this
+command, and disk images must not be edited concurrently.
+
+Use the I<--ro> (read-only) option to use C<$name> safely if the disk
+image or virtual machine might be live. You may see strange or
+inconsistent results if running concurrently with other changes, but
+with this option you won't risk disk corruption.";
+
$content .= "\n\n=head1 LICENSE\n\n";
foreach (@licenses) {
@@ -412,6 +475,14 @@ foreach (@licenses) {
$content .= "\n\n$reporting_bugs";
+if ($warning eq "general") {
+ $content =~ s/^=head1 DESCRIPTION/=head1 WARNING\n\n$warning_general\n\n=head1
DESCRIPTION/m or die;
+}
+elsif ($warning eq "ro-option") {
+ $content =~ s/^=head1 DESCRIPTION/=head1 WARNING\n\n$warning_ro_option\n\n=head1
DESCRIPTION/m or die;
+}
+# else do nothing for $warning "custom", "safe" or
"not-set"
+
# Output man page.
SUBMAN: {
package Podwrapper::Man;
--
2.5.0