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 (consisency, organization)
	-do this in cmatrix.c logic and usage as well
- 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

Fixes: #87, #105, and #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,146 @@
+.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 m
+Lambda mode
+.It Ic n
+Turn off bold characters
+.It Ic p , Ic P
+Pause
+.It Ic q
+Quit
+.It Ic r
+Rainbow mode
+.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 [email protected]
+for Linux in 1999.
+.Sh CAVEATS
+This is a fan made project, the Matrix movie is owned by completely
+unrelated trademark holders.
+.Sh BUGS
+The color black does not work.