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

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

[kristaps]

Log Message:
-----------
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.

Modified Files:
--------------
    mdocml:
        Makefile

Added Files:
-----------
    mdocml:
        man.cgi.7

Revision Data
-------------
--- /dev/null
+++ 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 .
Index: Makefile
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/Makefile,v
retrieving revision 1.381
retrieving revision 1.382
diff -LMakefile -LMakefile -u -p -r1.381 -r1.382
--- Makefile
+++ 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 \
--
 To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv