Doc: Manual and usage overhaul

- cmatrix.1 > cmatrix.6 (screensavers traditionally filed as games)
- rewrite in mdoc(7)
- write document description for visibility in manual searches
- maintain synopsis, options, and keystrokes
- write vendor neutral description of the program
- add examples including vendor neutral examples
- move homepage to SEE ALSO, link it, and relevant pages
- add terse HISTORY
- make program usage output consistent with the maintenance above

Fixes: abishekvashok#87, abishekvashok#105, and abishekvashok#162

CMakeLists.txt

@@ -69,7 +69,7 @@ add_executable(cmatrix cmatrix.c)
 target_link_libraries(cmatrix ${CURSES_LIBRARIES})
 
 install(TARGETS cmatrix DESTINATION ${CMAKE_INSTALL_BINDIR})
-install(FILES cmatrix.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
+install(FILES cmatrix.6 DESTINATION ${CMAKE_INSTALL_MANDIR}/man6)
 
 if     (UNIX)
 	foreach    (CONSOLE_FONTS_DIR ${CONSOLE_FONTS_DIRS})

Makefile.am

@@ -1,7 +1,7 @@
 bin_PROGRAMS = cmatrix
 cmatrix_SOURCES = cmatrix.c
 
-man_MANS = cmatrix.1
+man_MANS = cmatrix.6
 
 if MATRIX_FONTS
 BUILD_FONTS = 1
@@ -11,7 +11,7 @@ endif
 
 EXTRA_DIST =	COPYING INSTALL install-sh \
 		missing mkinstalldirs matrix.fnt \
-		matrix.psf.gz mtx.pcf cmatrix.1 cmatrix.spec
+		matrix.psf.gz mtx.pcf cmatrix.6 cmatrix.spec
 
 install-data-local:
 	@if test $(BUILD_FONTS) = 1; then \

cmatrix.6

@@ -0,0 +1,140 @@
+.Dd April 5, 2024
+.Dt CMATRIX 6
+.Os
+.Sh NAME
+.Nm cmatrix
+.Nd Matrix digital rain terminal screensaver
+.Sh SYNOPSIS
+.Nm
+.Op Fl \&?abBcfhklLmnorsVx
+.Op Fl C Ar color
+.Op Fl M Ar message
+.Op Fl t Ar tty
+.Op Fl u Ar delay
+.Sh DESCRIPTION
+The
+.Nm
+utility shows random 8-color characters raining down a terminal, at a
+user-defined speed, either at the same rate or asyncronously.
+.Pp
+The following command-line options are available:
+.Pp
+.Bl -tag -width "-M message" -compact
+.It Fl a
+Asynchronous scroll
+.It Fl b
+Bold characters on
+.It Fl B
+All bold characters, overrides
+.Fl b
+.It Fl c
+Use Japanese characters, requires appropriate font
+.It Fl C Ar color
+.Sq Ar green
+Use one of the eight
+.Ar color Ns s in the table below
+.It Fl f
+Force the
+.Va $TERM
+type to be on
+.It Fl h , Fl \&?
+Print usage and exit
+.It Fl k
+Change characters while scrolling, cannot combine with
+.Fl o
+.It Fl l
+Linux mode, use matrix console font
+.It Fl L
+Lock mode, can be
+.Xr kill 1 Ns ed
+from another terminal
+.It Fl m
+Lambda mode, every character becomes a lambda
+.It Fl M Ar message
+Add centered
+.Ar message
+overriding
+.Fl L Ns Ap s
+default
+.It Fl n
+No bold characters, overrides
+.Fl b
+and
+.Fl B
+.It Fl o
+Use old-style scrolling
+.It Fl r
+Rainbow mode, rainbow colored characters
+.It Fl s
+Screensaver mode, exits on first keystroke
+.It Fl t Ar tty
+Set tty to use
+.It Fl u Ar delay
+.Sq Ar 4
+Screen update delay
+.Ar 0 Ns Pf - Ar 9
+.It Fl V
+Print version information and exit
+.It Fl x
+X window mode, use if your
+.Xr xterm 1
+is using mtx.pcf
+.El
+.Pp
+The following keystrokes are available during execution:
+.Pp
+.Bl -tag -width "! @ # $ % ^ & )" -compact
+.It Ic "! @ # $ % ^ & )"
+Switch scheme to corresponding
+.Ar color :
+.Pp
+.TS
+aw10 aw10.
+! red	@ green
+# yellow	$ blue
+% magenta	^ cyan
+& white	) black
+.TE
+.Pp
+.It Ic 0 Ns Pf - Ic 9
+Set update delay
+.It Ic a
+Toggle asynchronous scroll
+.It Ic b
+Random bold characters
+.It Ic B
+All bold characters
+.It Ic n
+Turn off bold characters
+.It Ic p , Ic P
+Pause
+.It Ic q
+Quit
+.El
+.Sh EXAMPLES
+Interactive mode with asynchronous, partially-bold, red rain:
+.Dl $ cmatrix -ab -C red -u 2
+.Pp
+Interactive mode with asynchronous, partially-bold and Japanese rain:
+.Dl $ cmatrix -abc
+.Pp
+Screensaver mode emulating the classic from Windows/Mac:
+.Dl $ cmatrix -os
+.Pp
+Most realistic emulation of original movie:
+.Dl $ cmatrix -abcl
+.Sh SEE ALSO
+.Xr kill 1 ,
+.Xr xterm 1 ,
+.Xr ncurses 3
+.Pp
+.Lk http://www.github.com/abishekvashok/cmatrix Homepage
+.Sh HISTORY
+The
+.Nm
+utility was originally written by
+.An Chris Allegretta Aq Mt chrisa@asty.org
+for Linux in 1999.
+.Sh CAVEATS
+This is a fan made project, the Matrix movie is owned by completely
+unrelated trademark holders.

cmatrix.c

@@ -147,27 +147,27 @@ void c_die(char *msg, ...) {
 }
 
 void usage(void) {
-    printf(" Usage: cmatrix -[abBcfhlsmVxk] [-u delay] [-C color] [-t tty] [-M message]\n");
+    printf(" Usage: cmatrix [-\?abBcfhklLmnorsVx] [-C color] [-M message] [-t tty] [-u delay]\n");
     printf(" -a: Asynchronous scroll\n");
     printf(" -b: Bold characters on\n");
-    printf(" -B: All bold characters (overrides -b)\n");
-    printf(" -c: Use Japanese characters as seen in the original matrix. Requires appropriate fonts\n");
-    printf(" -f: Force the linux $TERM type to be on\n");
-    printf(" -l: Linux mode (uses matrix console font)\n");
-    printf(" -L: Lock mode (can be closed from another terminal)\n");
+    printf(" -B: All bold characters, overrides -b\n");
+    printf(" -c: Use Japanese characters, requires appropriate font\n");
+    printf(" -C [color]: \'green\' Use this color\n");
+    printf(" -f: Force the $TERM type to be on\n");
+    printf(" -h, \?: Print usage and exit\n");
+    printf(" -k: Change characters while scrolling, cannot combine with -o\n");
+    printf(" -l: Linux mode, use matrix console font\n");
+    printf(" -L: Lock mode, can be kill(1)ed from another terminal\n");
+    printf(" -m: Lambda mode, every character becomes a lambda\n");
+    printf(" -M [message]: Add centered message overriding -L's default\n");
+    printf(" -n: No bold characters, overrides -b and -B\n");
     printf(" -o: Use old-style scrolling\n");
-    printf(" -h: Print usage and exit\n");
-    printf(" -n: No bold characters (overrides -b and -B, default)\n");
-    printf(" -s: \"Screensaver\" mode, exits on first keystroke\n");
-    printf(" -x: X window mode, use if your xterm is using mtx.pcf\n");
-    printf(" -V: Print version information and exit\n");
-    printf(" -M [message]: Prints your message in the center of the screen. Overrides -L's default message.\n");
-    printf(" -u delay (0 - 10, default 4): Screen update delay\n");
-    printf(" -C [color]: Use this color for matrix (default green)\n");
-    printf(" -r: rainbow mode\n");
-    printf(" -m: lambda mode\n");
-    printf(" -k: Characters change while scrolling. (Works without -o opt.)\n");
+    printf(" -r: Rainbow mode, rainbow colored characters\n");
+    printf(" -s: Screensaver mode, exits on first keystroke\n");
     printf(" -t [tty]: Set tty to use\n");
+    printf(" -u [delay]: \'4\' Screen update delay 0-9\n");
+    printf(" -V: Print version information and exit\n");
+    printf(" -x: X window mode, use if your xterm(1) is using mtx.pcf\n");
 }
 
 void version(void) {