From 0061ffc6cedfb719db5fc3d38ad81da89018a6fe 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

Signed-off-by: David Nind <david@davidnind.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
(cherry picked from commit 215b29a737eff191477306581b8b3a1579adc9e3)
Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
---
 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 e06b9124ab..ede37ba900 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.
@@ -154,8 +173,6 @@ This is to prevent an accidental 'writeoff all' operation. Please note that
 --category-code must be accompanied by another filter - the script will not
 run if this is the only filter provided.
 
-=head1 OPTIONS
-
 =over
 
 =item B<-h|--help>
@@ -198,11 +215,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