version 1.1, 2011/11/26 19:54:13 |
version 1.8, 2017/03/18 19:56:01 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" 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 |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Os |
.Os |
.Sh NAME |
.Sh NAME |
.Nm catman |
.Nm catman |
.Nd update a man.cgi manpage cache |
.Nd format all manual pages below a directory |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm catman |
.Nm catman |
.Op Fl fv |
.Op Fl I Cm os Ns = Ns Ar name |
.Op Fl M Ar manpath |
.Op Fl T Ar output |
.Op Fl m Ar manpath |
.Ar srcdir dstdir |
.Op Fl o Ar path |
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
utility updates cached manpages for a jailed man.cgi. |
utility assumes that all files below |
Its arguments are as follows: |
.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 |
.It Fl I Cm os Ns = Ns Ar name |
Force an update to all files. |
Override the default operating system |
.It Fl v |
.Ar name |
Print each file being updated. |
for the |
.It Fl M Ar manpath |
.Xr mdoc 7 |
Use the colon-separated path instead of the default list of paths |
.Ic \&Os |
searched for |
and for the |
.Xr mandocdb 8 |
.Xr man 7 |
databases. |
.Ic TH |
Invalid paths, or paths without manual databases, are ignored. |
macro. |
.It Fl m Ar manpath |
.It Fl T Ar output |
Append the colon-separated paths to the list of paths searched |
Output format. |
for |
The |
.Xr mandocdb 8 |
.Ar output |
databases. |
argument can be |
Invalid paths, or paths without manual databases, are ignored. |
.Cm ascii , |
.It Fl o Ar path |
.Cm utf8 , |
Update into the directory tree under |
or |
.Ar path . |
.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 |
.Sh IMPLEMENTATION NOTES |
By default, |
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 |
implementations. |
.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. |
|
.Sh EXIT STATUS |
.Sh EXIT STATUS |
.Ex -std |
.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 |
.Sh SEE ALSO |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
.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 |
.Nm |
utility was written by |
are incompatible with each other because each caters to the needs |
.An Kristaps Dzonsons , |
of a specific operating system, for example regarding directory |
.Mt kristaps@bsd.lv . |
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. |