Bug 11344

Summary: Perldoc issues in misc/cronjobs/advance_notices.pl
Product: Koha Reporter: Barton Chittenden <bartonski>
Component: Command-line UtilitiesAssignee: James O'Keeffe <jamespfk>
Status: CLOSED FIXED QA Contact: Marcel de Rooy <m.de.rooy>
Severity: minor    
Priority: P5 - low CC: andrewfh, caroline.cyr-la-rose, fridolin.somers, jamespfk, jonathan.druart, katrin.fischer, m.de.rooy, victor
Version: masterKeywords: Academy
Hardware: All   
OS: All   
Change sponsored?: --- Patch complexity: Trivial patch
Documentation contact: Documentation submission:
Text to go in the release notes:
Version(s) released in:
21.05.00,20.11.03,20.05.09,19.11.15
Attachments: Bug 11344: Perldoc issues in misc/cronjobs/advance_notices.pl
Bug 11344: Perldoc issues in misc/cronjobs/advance_notices.pl
Bug 11344: Perldoc issues in misc/cronjobs/advance_notices.pl
Bug 11344: (QA follow-up) Fix empty section warning

Description Barton Chittenden 2013-12-05 17:47:00 UTC
perldoc misc/cronjobs/advance_notices.pl shows the following:

NAME
       advance_notices.pl - cron script to put item due reminders into message queue

SYNOPSIS
       ./advance_notices.pl -c

       or, in crontab: 0 1 * * * advance_notices.pl -c

DESCRIPTION
       This script prepares pre-due and item due reminders to be sent to patrons. It queues them in the message queue, which is processed by the process_message_queue.pl cronjob. The type and timing
       of the messages can be configured by the patrons in their "My Alerts" tab in the OPAC.

NAME
       advance_notices.pl - prepare messages to be sent to patrons for nearly due, or due, items

SYNOPSIS
       advance_notices.pl
         [ -n ][ -m <number of days> ][ --itemscontent <comma separated field list> ][ -c ]

OPTIONS
       --help  Print a brief help message and exits.

       --man   Prints the manual page and exits.

       -v      Verbose. Without this flag set, only fatal errors are reported.

       -n      Do not send any email. Advanced or due notices that would have been sent to the patrons are printed to standard out.

       -m      Defines the maximum number of days in advance to send advance notices.

       --itemscontent
               comma separated list of fields that get substituted into templates in places of the <<items.content>> placeholder. This defaults to due date,title,author,barcode

               Other possible values come from fields in the biblios, items and issues tables.

DESCRIPTION
       This script is designed to alert patrons when items are due, or coming due

...


===============================================

Issues:

NAME
SYNOPSIS
DESCRIPTION

Occur twice. The sections are not duplicates. One version should be chosen for each section.

-c (Confirm that the user has read and configured this script.) is not documented in OPTIONS.

Here are the comments where $confirm is defined, as well as the call to GetOptions:

   161  # These are defaults for command line options.
   162  my $confirm;                                                        # -c: Confirm that the user has read and configured this script.
   163  # my $confirm     = 1;                                                # -c: Confirm that the user has read and configured this script.
   164  my $nomail;                                                         # -n: No mail. Will not send any emails.
   165  my $mindays     = 0;                                                # -m: Maximum number of days in advance to send notices
   166  my $maxdays     = 30;                                               # -e: the End of the time period
   167  my $verbose     = 0;                                                # -v: verbose
   168  my $itemscontent = join(',',qw( date_due title author barcode ));
   169  
   170  my $help    = 0;
   171  my $man     = 0;
   172  
   173  GetOptions(
   174              'help|?'         => \$help,
   175              'man'            => \$man,
   176              'c'              => \$confirm,
   177              'n'              => \$nomail,
   178              'm:i'            => \$maxdays,
   179              'v'              => \$verbose,
   180              'itemscontent=s' => \$itemscontent,
   181         )or pod2usage(2);
   182  pod2usage(1) if $help;
   183  pod2usage( -verbose => 2 ) if $man;;
Comment 1 James O'Keeffe 2021-01-19 21:24:30 UTC
Created attachment 115363 [details] [review]
Bug 11344: Perldoc issues in misc/cronjobs/advance_notices.pl

This patch removes the double ups in the perldoc of the above file,
     deleting the less clear double ups. The missing "-c" in OPTIONS
     appears to have been fixed in an earlier patch (it is there
             already).

Task Plan:
1. Run perldoc misc/cronjobs/advance_notices.pl in the terminal. Note
the double ups of NAME, SYNOPSIS, and DESCRIPTION
2. Apply the patch
3. Run the command again. The double ups should be gone, with the more
clear version of each of NAME, SYNOPSIS, and DESCRIPTION remaining.
Comment 2 Katrin Fischer 2021-01-21 18:12:13 UTC
Created attachment 115586 [details] [review]
Bug 11344: Perldoc issues in misc/cronjobs/advance_notices.pl

This patch removes the double ups in the perldoc of the above file,
     deleting the less clear double ups. The missing "-c" in OPTIONS
     appears to have been fixed in an earlier patch (it is there
             already).

Task Plan:
1. Run perldoc misc/cronjobs/advance_notices.pl in the terminal. Note
the double ups of NAME, SYNOPSIS, and DESCRIPTION
2. Apply the patch
3. Run the command again. The double ups should be gone, with the more
clear version of each of NAME, SYNOPSIS, and DESCRIPTION remaining.

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Comment 3 Katrin Fischer 2021-01-21 18:13:07 UTC
I believe this is a good step in the right direction!

There is a note in the QA tools about a POD error still:

 FAIL	misc/cronjobs/advance_notices.pl
   OK	  critic
   OK	  forbidden patterns
   OK	  git manipulation
   FAIL	  pod
		*** WARNING: empty section in previous paragraph  in file misc/cronjobs/advance_notices.pl

If you get a chance today, please check if you can fix this as well!
Comment 4 Marcel de Rooy 2021-01-22 09:05:41 UTC
Created attachment 115667 [details] [review]
Bug 11344: Perldoc issues in misc/cronjobs/advance_notices.pl

This patch removes the double ups in the perldoc of the above file,
     deleting the less clear double ups. The missing "-c" in OPTIONS
     appears to have been fixed in an earlier patch (it is there
             already).

Task Plan:
1. Run perldoc misc/cronjobs/advance_notices.pl in the terminal. Note
the double ups of NAME, SYNOPSIS, and DESCRIPTION
2. Apply the patch
3. Run the command again. The double ups should be gone, with the more
clear version of each of NAME, SYNOPSIS, and DESCRIPTION remaining.

Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 5 Marcel de Rooy 2021-01-22 09:05:44 UTC
Created attachment 115668 [details] [review]
Bug 11344: (QA follow-up) Fix empty section warning

*** WARNING: empty section in previous paragraph at line 28 in file misc/cronjobs/advance_notices.pl

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 6 Jonathan Druart 2021-01-22 13:29:49 UTC
We lost the reference to the crontab, was it expected?
Comment 7 Jonathan Druart 2021-01-27 13:37:11 UTC
Pushed to master for 21.05, thanks to everybody involved!
Comment 8 Fridolin Somers 2021-01-29 14:34:22 UTC
Pushed to 20.11.x for 20.11.03
Comment 9 Andrew Fuerste-Henry 2021-02-04 21:30:22 UTC
Pushed to 20.05.x for 20.05.09
Comment 10 Victor Grousset/tuxayo 2021-02-09 21:22:25 UTC
Backported: Pushed to 19.11.x branch for 19.11.15