Style message about legacy man(7) date format in mdoc(7) documents

[mandoc.git] / catman.8

diff --git a/catman.8 b/catman.8
index 4b6b5853566554c2e17782db6faf2e17f323f25a..903fa1fa82c928b416746b58943afa8357830665 100644 (file)
--- a/catman.8
+++ b/catman.8
@@ -1,6 +1,6 @@
-.\"    $Id: catman.8,v 1.2 2011/12/04 22:52:50 kristaps Exp $
+.\"    $Id: catman.8,v 1.8 2017/03/18 19:56:01 schwarze Exp $

 .\"
 .\"

-.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" 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
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above


@@ -14,71 +14,173 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: December 4 2011 $
+.Dd $Mdocdate: March 18 2017 $

 .Dt CATMAN 8
 .Os
 .Sh NAME
 .Nm catman
 .Dt CATMAN 8
 .Os
 .Sh NAME
 .Nm catman

-.Nd update a man.cgi manpage cache
+.Nd format all manual pages below a directory

 .Sh SYNOPSIS
 .Nm catman
 .Sh SYNOPSIS
 .Nm catman

-.Op Fl fv
-.Op Fl M Ar manpath
-.Op Fl m Ar manpath
-.Op Fl o Ar path
+.Op Fl I Cm os Ns = Ns Ar name
+.Op Fl T Ar output
+.Ar srcdir dstdir

 .Sh DESCRIPTION
 The
 .Nm
 .Sh DESCRIPTION
 The
 .Nm

-utility updates cached manpages for a jailed
-.Xr man.cgi 7 .
-Its arguments are as follows:
+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
 .Bl -tag -width Ds

-.It Fl f
-Force an update to all files.
-.It Fl v
-Print each file being updated.
-.It Fl M Ar manpath
-Use the colon-separated path instead of the default list of paths
-searched for
-.Xr mandocdb 8
-databases.
-Invalid paths, or paths without manual databases, are ignored.
-.It Fl m Ar manpath
-Append the colon-separated paths to the list of paths searched
-for
-.Xr mandocdb 8
-databases.
-Invalid paths, or paths without manual databases, are ignored.
-.It Fl o Ar path
-Update into the directory tree under
-.Ar path .
+.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
 .El

-.Pp
-By default,
+.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
 .Nm

-searches for
-.Xr mandocdb 8
-databases in the default paths stipulated by
-.Xr man 1
-and updates the cache in
-.Pa /var/www/cache/man.cgi .
-.Pp
-An update occurs when a
-.Xr mandocdb 8
-database is older than the cached copy.
-Cached manual pages are only updated if older than the master copy.
-If
-.Fl f
-is specified, all files are updated.
+implementations.

 .Sh EXIT STATUS
 .Ex -std
 .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 ,
 .Sh SEE ALSO
 .Xr mandoc 1 ,

-.Xr man.cgi 7 ,
-.Xr mandocdb 8
+.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
 .Sh AUTHORS

+.An -nosplit
+The first
+.Nm
+implementation was a short shell script by
+.An Christoph Robitschko
+in July 1993.
+.Pp

 The
 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
 .Nm

-utility was written by
-.An Kristaps Dzonsons ,
-.Mt kristaps@bsd.lv .
+always reformats each page, even if the formatted version is newer
+than the source version.