From 2fce8e06466398dfcbdd2263b8101c59d88b29a2 Mon Sep 17 00:00:00 2001
From: Julian Maurice <julian.maurice@biblibre.com>
Date: Fri, 16 Feb 2024 09:23:13 +0100
Subject: [PATCH] Bug 34077: Improve documentation and error messages of
 writeoff_debts.pl

* Change the SYNOPSIS to better describe the different ways to use the
  script
* Only show the SYNOPSIS when options used are wrong (unknown option,
  no filter options, or neither -c nor -v)
* Show the options details only with --help
* Clarify the fact that -v is required when -c is not supplied in the
  description of both options
* Print a specific error message for the following cases:
  * no filters options
  * neither -c nor -v was supplied
---
 misc/cronjobs/writeoff_debts.pl | 37 ++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/misc/cronjobs/writeoff_debts.pl b/misc/cronjobs/writeoff_debts.pl
index 8d808185391..5ac7ca89fc1 100755
--- a/misc/cronjobs/writeoff_debts.pl
+++ b/misc/cronjobs/writeoff_debts.pl
@@ -21,10 +21,21 @@ GetOptions(
     'cc|category_code|category-code:s' => \@category_code,
     'f|file:s'                         => \$file,
     'c|confirm'                        => \$confirm,
-);
+) or pod2usage(2);
+
+pod2usage(1) if $help;
+
+if ( !$confirm && !$verbose ) {
+    say STDERR "Missing required option: either --verbose or --confirm must be supplied";
+    pod2usage(2);
+}
+
 @type = split( /,/, join( ',', @type ) );
 
-pod2usage(1) if ( $help || !$confirm && !$verbose || !$file && !@type && !$before && !$after );
+if ( !$file && !@type && !$before && !$after ) {
+    say STDERR "Missing required filter option: at least one filter option should be used";
+    pod2usage(2);
+}
 
 my $where = { 'amountoutstanding' => { '>' => 0 } };
 my $attr = {};
@@ -141,10 +152,18 @@ writeoff_debts.pl
 
 =head1 SYNOPSIS
 
-  ./writeoff_debts.pl --added_before DATE --type OVERDUE --file REPORT --confirm
+  writeoff_debts.pl --confirm [--verbose] <filter options>
+  writeoff_debts.pl --verbose <filter options>
+  writeoff_debts.pl --help
+
+  <filter options> are:
+      [--type <type>] [--file <file>] [--added-before <date>]
+      [--added-after <date>] [--category-code <category code>]
 
 This script batch waives debts.
 
+=head1 OPTIONS
+
 The options to select the debt records to writeoff are cumulative. For
 example, supplying both --added_before and --type specifies that the
 accountline must meet both conditions to be selected for writeoff.
@@ -152,8 +171,6 @@ accountline must meet both conditions to be selected for writeoff.
 You must pass at least one of the filtering options for the script to run.
 This is to prevent an accidental 'writeoff all' operation.
 
-=head1 OPTIONS
-
 =over
 
 =item B<-h|--help>
@@ -194,11 +211,17 @@ criteria.
 
 This flag set the script to output logging for the actions it will perform.
 
+The B<-v> option is mandatory if B<-c> is not supplied.
+
+It can be repeated for increased verbosity.
+
 =item B<-c|--confirm>
 
 This flag must be provided in order for the script to actually
-writeoff debts.  If it is not supplied, the script will
-only report on the accountline records it would have been written off.
+writeoff debts.
+
+If it is not supplied, the B<-v> option is required. The script will then only
+report on the accountline records it would have been written off.
 
 =back
 
-- 
2.30.2