Doc: Manual, usage, and logic cleanup

- cmatrix.1 > cmatrix.6 (other screensavers seem filed as games)
- rewrite manual in mdoc(7) according to its best practices
- write document description for visibility in manual searches
- maintain synopsis, options, and keystrokes (consisency, organization, nits)
	-do this in cmatrix.c usage for consistency
		- do this in cmatrix.c logic for maintainability
- write vendor neutral description of the program
- add EXAMPLES including updated readme and vendor neutral examples
- add SEE ALSO, including homepage as well as relevant manual pages
- add HISTORY mentioning original author, date, and vendor
- add CAVEATS mentioning trademarks
- revise BUGS, black doesn't work, and cmatrix no longer has high utilization

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,148 @@
+.Dd April 8, 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 digital rain in a terminal.
+It supports a selection of characters, colors, rates, and speeds,
+as well as lock, interactive, and screensaver modes.
+.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 this
+.Ar color
+of the eight colors 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.