new manual pages for catman(8) and mandocd(8)

3 files changed, 391 insertions, 1 deletions

diff --git a/Makefile b/Makefile
index c5057573..77fda29e 100644
--- a/Makefile
+++ b/Makefile
@@ -130,6 +130,7 @@ DISTFILES	 = INSTALL \
 		   NEWS \
 		   TODO \
 		   apropos.1 \
+		   catman.8 \
 		   cgi.h.example \
 		   compat_fts.h \
 		   compat_ohash.h \
@@ -172,6 +173,7 @@ DISTFILES	 = INSTALL \
 		   mandoc_html.3 \
 		   mandoc_malloc.3 \
 		   mandoc_ohash.h \
+		   mandocd.8 \
 		   mansearch.3 \
 		   mansearch.h \
 		   mchars_alloc.3 \
@@ -307,6 +309,7 @@ WWW_MANS	 = apropos.1.html \
 		   man.1.html \
 		   mandoc.1.html \
 		   soelim.1.html \
+		   man.cgi.3.html \
 		   mandoc.3.html \
 		   mandoc_escape.3.html \
 		   mandoc_headers.3.html \
@@ -320,11 +323,12 @@ WWW_MANS	 = apropos.1.html \
 		   eqn.7.html \
 		   man.7.html \
 		   mandoc_char.7.html \
+		   mandocd.8.html \
 		   mdoc.7.html \
 		   roff.7.html \
 		   tbl.7.html \
+		   catman.8.html \
 		   makewhatis.8.html \
-		   man.cgi.3.html \
 		   man.cgi.8.html \
 		   man.h.html \
 		   manconf.h.html \
@@ -421,7 +425,9 @@ cgi-install: man.cgi
 
 catman-install: mandocd catman
 	mkdir -p $(DESTDIR)$(SBINDIR)
+	mkdir -p $(DESTDIR)$(MANDIR)/man8
 	$(INSTALL_PROGRAM) mandocd catman $(DESTDIR)$(SBINDIR)
+	$(INSTALL_MAN) mandocd.8 catman.8 $(DESTDIR)$(MANDIR)/man8
 
 Makefile.local config.h: configure ${TESTSRCS}
 	@echo "$@ is out of date; please run ./configure"
diff --git a/catman.8 b/catman.8
new file mode 100644
index 00000000..7aeb1a5a
--- /dev/null
+++ b/catman.8
@@ -0,0 +1,186 @@
+.\"	$Id$
+.\"
+.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt CATMAN 8
+.Os
+.Sh NAME
+.Nm catman
+.Nd format all manual pages below a directory
+.Sh SYNOPSIS
+.Nm catman
+.Op Fl I Cm os Ns = Ns Ar name
+.Op Fl T Ar output
+.Ar srcdir dstdir
+.Sh DESCRIPTION
+The
+.Nm
+utility assumes that all files below
+.Ar srcdir
+are manual pages in
+.Xr mdoc 7
+and
+.Xr man 7
+format and formats all of them, storing the formatted versions in
+the same relative paths below
+.Ar dstdir .
+Subdirectories of
+.Ar dstdir
+are created as needed.
+Existing files are not explicitly deleted, but possibly overwritten.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl I Cm os Ns = Ns Ar name
+Override the default operating system
+.Ar name
+for the
+.Xr mdoc 7
+.Ic Os
+and for the
+.Xr man 7
+.Ic TH
+macro.
+.It Fl T Ar output
+Output format.
+The
+.Ar output
+argument can be
+.Cm ascii ,
+.Cm utf8 ,
+or
+.Cm html ;
+see
+.Xr mandoc 1 .
+In
+.Cm html
+output mode, the
+.Cm fragment
+output option is implied.
+Other output options are not supported.
+.El
+.Sh IMPLEMENTATION NOTES
+Since this version avoids
+.Xr fork 2
+and
+.Xr exec 3
+overhead and uses the much faster
+.Sy mandoc
+parsers and formatters rather than
+.Sy groff ,
+it may be about one order of magnitude faster than other
+.Nm
+implementations.
+.Sh EXIT STATUS
+.Ex -std
+.Pp
+Possible errors include:
+.Bl -bullet
+.It
+missing, invalid, or excessive command line arguments
+.It
+failure to change the current working directory to
+.Ar srcdir
+.It
+failure to open
+.Ar dstdir
+.It
+communication failure with
+.Xr mandocd 8
+.It
+resource exhaustion, for example file descriptor, process table,
+or memory exhaustion
+.El
+.Pp
+Except for memory exhaustion and similar system-level failures,
+failures while trying to open, read, parse, or format individual
+manual pages, to save individual formatted files to the file system,
+or even to create directories do not cause
+.Nm
+to return an error exit status.
+In such cases,
+.Nm
+will simply continue with the next file or subdirectory.
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr mandocd 8
+.Sh HISTORY
+A
+.Nm
+utility first appeared in
+.Fx 1.0 .
+Other, incompatible implementations appeared in
+.Nx 1.0
+and in
+.Sy man-db No 2.2 .
+.Pp
+This version appeared in version 1.14.1 of the
+.Sy mandoc
+toolkit.
+.Sh AUTHORS
+.An -nosplit
+The first
+.Nm
+implementation was a short shell script by
+.An Christoph Robitschko
+in July 1993.
+.Pp
+The
+.Nx
+implementations were written by
+.An J. T. Conklin Aq Mt jtc@netbsd.org
+in 1993,
+.An Christian E. Hopps Aq Mt chopps@netbsd.org
+in 1994,
+and
+.An Dante Profeta Aq Mt dante@netbsd.org
+in 1999; the
+.Sy man-db
+implementation by
+.An Graeme W. Wilford
+in 1994; and the
+.Fx
+implementations by
+.An Wolfram Schneider Aq Mt wosch@freebsd.org
+in 1995 and
+.An John Rochester Aq Mt john@jrochester.org
+in 2002.
+.Pp
+The concept of the present version was designed and implemented by
+.An Michael Stapelberg Aq Mt stapelberg@debian.org
+in 2017.
+Option and argument handling and directory iteration was added by
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
+.Sh CAVEATS
+All versions of
+.Nm
+are incompatible with each other because each caters to the needs
+of a specific operating system, for example regarding directory
+structures and file naming conventions.
+.Pp
+This version is more flexible than the others in so far as it does
+not assume any particular directory structure or naming convention.
+That flexibility comes at the price of not being able to change the
+names and relative paths of the source files when reusing them to
+store the formatted files, of not supporting any configuration file
+formats or environment variables, and of being unable to scan for
+and remove junk files in
+.Ar dstdir .
+.Pp
+Currently,
+.Nm
+always reformats each page, even if the formatted version is newer
+than the source version.
diff --git a/mandocd.8 b/mandocd.8
new file mode 100644
index 00000000..36b423c6
--- /dev/null
+++ b/mandocd.8
@@ -0,0 +1,198 @@
+.\"	$Id$
+.\"
+.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt MANDOCD 8
+.Os
+.Sh NAME
+.Nm mandocd
+.Nd server process to format manual pages in batch mode
+.Sh SYNOPSIS
+.Nm mandocd
+.Op Fl I Cm os Ns = Ns Ar name
+.Op Fl T Ar output
+.Ar socket_fd
+.Sh DESCRIPTION
+The
+.Nm
+utility formats many manual pages without requiring
+.Xr fork 2
+and
+.Xr exec 3
+overhead in between.
+It does not require listing all the manuals to be formatted on the
+command line, and it supports writing each formatted manual to its
+own file descriptor.
+.Pp
+This server requires that a connected UNIX domain
+.Xr socket 2
+is already present at
+.Xr exec 3
+time.
+Consequently, it cannot be started from the
+.Xr sh 1
+command line because the shell cannot supply such a socket.
+Typically, the socket is created by the parent process using
+.Xr socketpair 2
+before calling
+.Xr fork 2
+and
+.Xr exec 3
+on
+.Nm .
+The parent process will pass the file descriptor number as an argument to
+.Xr exec 3 ,
+formatted as a decimal ASCII-encoded integer.
+See
+.Xr catman 8
+for a typical implementation of a parent process.
+.Pp
+.Nm
+loops reading one-byte messages with
+.Xr recvmsg 2
+from the file descriptor number
+.Ar socket_fd .
+It ignores the byte read and only uses the out-of-band auxiliary
+.Vt struct cmsghdr
+control data, typically supplied by the calling process using
+.Xr CMSG_FIRSTHDR 3 .
+The parent process is expected to pass three file descriptors
+with each dummy byte.
+The first one is used for
+.Xr mdoc 7
+or
+.Xr man 7
+input, the second one for formatted output, and the third one
+for error output.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl I Cm os Ns = Ns Ar name
+Override the default operating system
+.Ar name
+for the
+.Xr mdoc 7
+.Ic Os
+and for the
+.Xr man 7
+.Ic TH
+macro.
+.It Fl T Ar output
+Output format.
+The
+.Ar output
+argument can be
+.Cm ascii ,
+.Cm utf8 ,
+or
+.Cm html ;
+see
+.Xr mandoc 1 .
+In
+.Cm html
+output mode, the
+.Cm fragment
+output option is implied.
+Other output options are not supported.
+.El
+.Pp
+After exhausting one input file descriptor, all three file descriptors
+are closed before reading the next dummy byte and control message.
+.Pp
+When a zero-byte message is read, when the
+.Ar socket_fd
+is closed by the parent process,
+or when an error occurs,
+.Nm
+exits.
+.Sh EXIT STATUS
+.Ex -std
+.Pp
+A zero-byte message or a closed
+.Ar socket_fd
+is considered success.
+Possible errors include:
+.Bl -bullet
+.It
+missing, invalid, or excessive
+.Xr exec 3
+arguments
+.It
+.Xr recvmsg 2
+failure, for example due to
+.Er EMSGSIZE
+.It
+missing or unexpected control data, in particular a
+.Fa cmsg_level
+in the
+.Vt struct cmsghdr
+that differs from
+.Dv SOL_SOCKET ,
+a
+.Fa cmsg_type
+that differs from
+.Dv SCM_RIGHTS ,
+or a
+.Fa cmsg_len
+that is not three times the size of an
+.Vt int
+.It
+invalid file descriptors passed in the
+.Xr CMSG_DATA 3
+.It
+resource exhaustion, in particular
+.Xr dup 2
+or
+.Xr malloc 3
+failure
+.El
+.Pp
+Except for memory exhaustion and similar system-level failures,
+parsing and formatting errors do not cause
+.Nm
+to return an error exit status.
+Even after severe parsing errors,
+.Nm
+will simply accept and process the next input file descriptor.
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr mandoc 3 ,
+.Xr catman 8
+.Sh HISTORY
+The
+.Nm
+utility appeared in version 1.14.1 or the
+.Sy mandoc
+toolkit.
+.Sh AUTHORS
+.An -nosplit
+The concept was designed and implemented by
+.An Michael Stapelberg Aq Mt stapelberg@debian.org .
+The
+.Xr mandoc 3
+glue needed to make it a stand-alone process was added by
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
+.Sh CAVEATS
+If the parsed manual pages contain
+.Xr roff 7
+.Pf . Ic so
+requests,
+.Nm
+needs to be started with the current working directory set to the
+root of the manual page tree.
+Avoid starting it in directories that contain secret files in any
+subdirectories, in particular in the user starting it has read
+access to these secret files.