version 1.6, 2012/06/09 11:27:38 |
version 1.7, 2017/02/06 19:04:21 |
|
|
.\" $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 C Ar file |
.Op Fl T Ar output |
.Op Fl M Ar manpath |
.Ar srcdir dstdir |
.Op Fl m Ar manpath |
|
.Op Fl o Ar path |
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
utility updates cached manpages for a jailed |
utility assumes that all files below |
.Xr man.cgi 7 . |
.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 |
.Pp |
By default, |
The options are as follows: |
.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 |
|
Its arguments 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 C Ar file |
.Xr mdoc 7 |
Specify an alternative configuration |
.Ic Os |
.Ar file |
and for the |
in |
.Xr man 7 |
.Xr man.conf 5 |
.Ic TH |
format. |
macro. |
.It Fl M Ar manpath |
.It Fl T Ar output |
Use the colon-separated path instead of the default list of paths |
Output format. |
searched for |
The |
.Xr mandocdb 8 |
.Ar output |
databases. |
argument can be |
Invalid paths, or paths without manual databases, are ignored. |
.Cm ascii , |
.It Fl m Ar manpath |
.Cm utf8 , |
Prepend the colon-separated paths to the list of paths searched |
or |
for |
.Cm html ; |
.Xr mandocdb 8 |
see |
databases. |
.Xr mandoc 1 . |
Invalid paths, or paths without manual databases, are ignored. |
In |
.It Fl o Ar path |
.Cm html |
Update into the directory tree under |
output mode, the |
.Ar path . |
.Cm fragment |
|
output option is implied. |
|
Other output options are not supported. |
.El |
.El |
.Pp |
.Sh IMPLEMENTATION NOTES |
Cache updates occur when a |
Since this version avoids |
.Xr mandocdb 8 |
.Xr fork 2 |
database is older than the cached copy unless |
and |
.Fl f |
.Xr exec 3 |
is specified, in which case files are always considered out of date. |
overhead and uses the much faster |
Cached manual pages are only updated if older than the master copy. |
.Sy mandoc |
.Sh ENVIRONMENT |
parsers and formatters rather than |
.Bl -tag -width Ds |
.Sy groff , |
.It Ev MANPATH |
it may be about one order of magnitude faster than other |
Colon-separated paths modifying the default list of paths searched for |
.Nm |
manual databases. |
implementations. |
Invalid paths, or paths without manual databases, are ignored. |
|
Overridden by |
|
.Fl M . |
|
If |
|
.Ev MANPATH |
|
begins with a |
|
.Sq \&: , |
|
it is appended to the default list; |
|
else if it ends with |
|
.Sq \&: , |
|
it is prepended to the default list; else if it contains |
|
.Sq \&:: , |
|
the default list is inserted between the colons. |
|
If none of these conditions are met, it overrides the default list. |
|
.El |
|
.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 man.cgi 7 , |
.Xr mandocd 8 |
.Xr mandocdb 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. |