[BACK]Return to catman.8 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/catman.8 between version 1.4 and 1.7

version 1.4, 2011/12/24 22:37:16 version 1.7, 2017/02/06 19:04:21
Line 1 
Line 1 
 .\"     $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
Line 19 
Line 19 
 .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
 Its arguments are as follows:  are manual pages in
 .Bl -tag -width Ds  .Xr mdoc 7
 .It Fl f  and
 Force an update to all files.  .Xr man 7
 .It Fl v  format and formats all of them, storing the formatted versions in
 Print each file being updated.  the same relative paths below
 .It Fl C Ar file  .Ar dstdir .
 Specify an alternative configuration  Subdirectories of
 .Ar file  .Ar dstdir
 in  are created as needed.
 .Xr man.conf 5  Existing files are not explicitly deleted, but possibly overwritten.
 format.  
 .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  
 Prepend 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 .  
 .El  
 .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  
 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 ENVIRONMENT  
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Ev MANPATH  .It Fl I Cm os Ns = Ns Ar name
 Colon-separated paths modifying the default list of paths searched for  Override the default operating system
 manual databases.  .Ar name
 Invalid paths, or paths without manual databases, are ignored.  for the
 Overridden by  .Xr mdoc 7
 .Fl M .  .Ic Os
 If  and for the
 .Ev MANPATH  .Xr man 7
 begins with a  .Ic TH
 .Sq \&: ,  macro.
 it is appended to the default list;  .It Fl T Ar output
 else if it ends with  Output format.
 .Sq \&: ,  The
 it is prepended to the default list; else if it contains  .Ar output
 .Sq \&:: ,  argument can be
 the default list is inserted between the colons.  .Cm ascii ,
 If none of these conditions are met, it overrides the default list.  .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
   .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  .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.
Legend:
Removed from v.1.4  
changed lines
  Added in v.1.7
CVSweb