Make a small manual for how to run man.cgi.

This exists almost entirely to document that /tmp must exist in a jailed
Apache directory for dbopen() not to fail.  This was a massive headache
to track down.

diff --git a/Makefile b/Makefile
index 089831bc81aa89b7913681dbacdad0c50ea8b3bc..c4a8d67f7d9a736b25a3970c9eecc1b30742c61e 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -92,6 +92,7 @@ SRCS           = Makefile \
                   man.h \
                   man.7 \
                   man.c \
+                  man.cgi.7 \
                   man_hash.c \
                   man_html.c \
                   man_macro.c \

diff --git a/man.cgi.7 b/man.cgi.7
new file mode 100644 (file)
index 0000000..9ede2f1
--- /dev/null
+++ b/man.cgi.7
@@ -0,0 +1,78 @@
+.Dd $Mdocdate: November 24 2011 $
+.Dt MAN.CGI 7
+.Os
+.Sh NAME
+.Nm man.cgi
+.Nd cgi for manpage query and display
+.Sh SYNOPSIS
+.Nm
+.Sh DESCRIPTION
+The
+.Nm
+script queries and displays manual pages.
+It interfaces with
+.Xr mandocdb 8
+databases for query and with
+.Xr mandoc 1
+for display.
+This script operates in two modes: secure and insecure.
+.Bl -tag -width Ds
+.It insecure
+Act as a web-based
+.Xr apropos 1
+and
+.Xr mandoc 1 .
+This assumes full access to the file-system.
+It is not recommended for public-facing servers.
+.It secure
+Act on manual pages cached by
+.Xr manup 8 .
+A cached file tree is queried for pre-formatted manuals.
+.El
+.Pp
+To run in insecure mode, drop
+.Nm
+into your web-server's CGI directory.
+The environment variable
+.Ev INSECURE
+must be set.
+.Pp
+To run in secure mode, you must maintain a cache directory of
+preformatted manuals using
+.Xr manup 8 .
+If your web-server is running in a jail, the cache directory must be
+within the jail.
+Set the environment variable
+.Ev CACHE_DIR
+to this directory, which defaults to
+.Pa /cache/man.cgi .
+If you're running in a jailed web-server, make sure the
+.Pa /tmp
+directory exists and is writable.
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Er INSECURE
+Run in insecure mode.
+Not recommended.
+.It Er CACHE_DIR
+The absolute path of the
+.Xr manup 8
+cache directory.
+.El
+.Sh FILES
+The configuration file
+.Pa etc/man.conf
+must exist within the cache directory.
+This is built by
+.Xr manup 8 .
+.Sh SEE ALSO
+.Xr apropos 1 ,
+.Xr mandoc 1 ,
+.Xr manup 8 ,
+.Xr mandocdb 8
+.Sh AUTHORS
+The
+.Nm
+utility was written by
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .