From cf62d3ab94b313e2650bca0af5f0c1da00f1af3c Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Mon, 22 Jan 2024 05:56:45 -0800
Subject: [PATCH] Add ioccc-status.1, bug fix ioccc-status.sh

The man page is in /man/man1/. It is not clear to me if man/man1 should
be under another directory but that can be decided later and if
necessary it can be moved over. The man page has a few examples. More
could be contrived if necessary. It has no SEE ALSO section because it
is not clear to me what should be linked to (perhaps the IOCCC
website?). I felt like I should write this man page first, in
particular, because I wrote the script too and the benefit is I
discovered some bugs in the script as well that are now fixed.

The script only checked if the status.json file was readable but it did
not check if it is writable. It should check for both and it now does.
The exit code is the same as if the file does not exist, is not a
regular file or not readable: 1. It also now explicitly exits 0 at the
end of the script. The version was updated to

    IOCCC_STATUS_SCRIPT_VERSION="0.0.5-0 2024-01-22" # major.minor.release-patch YYYY-MM-DD

When fixing the script some things crossed my mind that might be worth
considering. First of all if dry-mode is specified (-N) does it really
need to have a status.json file arg specified? It might or might not.
Second should there be an option to create a new status.json file (if
the one does not exist)? These are perhaps worth considering and
wouldn't be hard to implement if these are desirable.
---
 bin/ioccc-status.sh     |   9 ++-
 man/man1/ioccc-status.1 | 150 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 157 insertions(+), 2 deletions(-)
 create mode 100644 man/man1/ioccc-status.1

diff --git a/bin/ioccc-status.sh b/bin/ioccc-status.sh
index 1eb1fcd4d..7f03d50db 100755
--- a/bin/ioccc-status.sh
+++ b/bin/ioccc-status.sh
@@ -24,7 +24,7 @@
 #
 # The -G option lets one set the path to grep(1).
 #
-export IOCCC_STATUS_SCRIPT_VERSION="0.0.4-0 2024-01-22" # major.minor.release-patch YYYY-MM-DD
+export IOCCC_STATUS_SCRIPT_VERSION="0.0.5-0 2024-01-22" # major.minor.release-patch YYYY-MM-DD
 
 SED="$(type -P sed)"
 GREP="$(type -P grep)"
@@ -129,13 +129,17 @@ if [[ ! -e $STATUS_JSON_FILE ]]; then
     exit 1
 fi
 if [[ ! -f $STATUS_JSON_FILE ]]; then
-    echo "$0: ERROR: status.json not a file: $STATUS_JSON_FILE" 1>&2
+    echo "$0: ERROR: status.json not a regular file: $STATUS_JSON_FILE" 1>&2
     exit 1
 fi
 if [[ ! -r $STATUS_JSON_FILE ]]; then
     echo "$0: ERROR: status.json not a readable file: $STATUS_JSON_FILE" 1>&2
     exit 1
 fi
+if [[ ! -w $STATUS_JSON_FILE ]]; then
+    echo "$0: ERROR: status.json is not a writable file: $STATUS_JSON_FILE" 1>&2
+    exit 1
+fi
 
 # check that $SED is an executable file
 if [[ ! -x "$SED" ]]; then
@@ -238,3 +242,4 @@ if [[ -n "$STATUS_FLAG" ]]; then
 	echo "$0: updated contest status to: \"$STATUS\"" 1>&2
     fi
 fi
+exit 0
diff --git a/man/man1/ioccc-status.1 b/man/man1/ioccc-status.1
new file mode 100644
index 000000000..52ae1e8e2
--- /dev/null
+++ b/man/man1/ioccc-status.1
@@ -0,0 +1,150 @@
+.\" section 1 man page for ioccc-status.sh
+.\"
+.\" This man page was first written by Cody Boone Ferguson for the IOCCC
+.\" in 2024.
+.\"
+.\" "Share and Enjoy!"
+.\"     --  Sirius Cybernetics Corporation Complaints Division, JSON spec department. :-)
+.\"
+.TH ioccc-status.sh 1 "22 January 2024" "ioccc-status.sh" "IOCCC website tools"
+.SH NAME
+.B ioccc-status.sh
+\- update the
+.B status.json
+file
+.SH SYNOPSIS
+.B ioccc-status.sh
+.RB [\| \-h \|]
+.RB [\| \-V \|]
+.RB [\| \-v
+.IR level \|]
+.RB [\| \-s
+.IR status \|]
+.RB [\| \-d \|]
+.RB [\| \-n \|]
+.RB [\| \-i
+.IR status_ver \|]
+.RB [\| \-N \|]
+.RB [\| \-S
+.IR sed \|]
+.RB [\| -G
+.IR grep \|]
+.IR status.json
+.SH DESCRIPTION
+.B ioccc-status.sh
+will update the IOCCC
+.B status.json
+file that shows the contest status (\fI"open"\fP or \fI"closed"\fP), the status date (when the
+.B status
+was last updated), the news date (when the
+.B news
+was last updated) and/or the
+.B status version\c
+, unless the dry\-mode (\c
+.BR \-N )
+option is specified. If dry\-mode is used then it will only show what would have changed.
+.SH OPTIONS
+.TP
+.B \-h
+Print help and exit.
+.TP
+.B \-V
+Print version and exit.
+.TP
+.BI \-v\  level
+Set verbosity level to
+.I level
+(def: 0). If level is 1 or higher it will show what file will be touched and what values will be updated, based on the options specified, assuming dry mode is not set and an option to update the file is used.
+.TP
+.BI \-s\  status
+Set
+.I status
+to \fB"open"\fP or \fB"closed"\fP. Any other value is an error.
+.TP
+.B \-d
+Update status date to the value of the shell command
+.BR date .
+.TP
+.B \-n
+Update latest news date to the value of the shell command
+.BR date .
+.TP
+.BI \-i\  status_version
+Update the status version. The version must match the regexp: '\fB^[0\-9]+\\\.[0\-9]+ [0\-9]{4}\-[0\-9]{2}\-[0\-9]{2}$\fP' and if it does not it is an error.
+.TP
+.BI \-S\  sed
+Set path to
+.BR sed (1).
+The default is from the command \fBtype -P sed\fP.
+.TP
+.BI \-G\  grep
+Set path to
+.BR grep (1).
+The default is from the command \fBtype -P grep\fP.
+.SH EXIT STATUS
+.TP
+0
+dry\-mode used or successfully updated the
+.B status.json
+file (or no update requested)
+.TQ
+1
+status.json file does not exist or is not a regular readable and writable file
+.TQ
+2
+help mode exit or print version mode exit
+.TQ
+3
+invalid command line (including
+.BR sed (1)
+or
+.BR grep (1)
+not being regular executable files)
+.SH NOTES
+.PP
+.B ioccc\-status.sh
+was written by
+.B Cody Boone Ferguson
+in 2023 to update/maintain the
+.B status.json
+file suggested to the IOCCC judges by \fBToni Mikkola (@Virtaava@home.social)\fP.
+.SH BUGS
+.PP
+A human wrote it? :\-)
+.PP
+Nevertheless, if you feel there is an issue with this tool you may open an issue at the GitHub issues page.
+.SH EXAMPLES
+.PP
+Run script to get help:
+.sp
+.RS
+.ft B
+ ./ioccc-status.sh
+
+ ./ioccc-status.sh \-h
+.ft R
+.RE
+.PP
+Dry\-mode run of updating the latest news date:
+.sp
+.RS
+.ft B
+ ./ioccc-status.sh \-n \-N ../status.json
+.ft R
+.RE
+.PP
+Update the latest news date:
+.sp
+.RS
+.ft B
+ ./ioccc-status.sh \-n ../status.json
+.ft R
+.RE
+.PP
+Set contest status to open with a new status version of \fB0.3 2024\-01\-22\fP:
+.sp
+.RS
+.ft B
+ ./ioccc-status.sh -s open -i '0.3 2024-01-22' ../status.json
+.ft R
+.RE