catman.8

   1 .\"     $Id: catman.8,v 1.8 2017/03/18 19:56:01 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: March 18 2017 $
  18 .Dt CATMAN 8
  19 .Os
  20 .Sh NAME
  21 .Nm catman
  22 .Nd format all manual pages below a directory
  23 .Sh SYNOPSIS
  24 .Nm catman
  25 .Op Fl I Cm os Ns = Ns Ar name
  26 .Op Fl T Ar output
  27 .Ar srcdir dstdir
  28 .Sh DESCRIPTION
  29 The
  30 .Nm
  31 utility assumes that all files below
  32 .Ar srcdir
  33 are manual pages in
  34 .Xr mdoc 7
  35 and
  36 .Xr man 7
  37 format and formats all of them, storing the formatted versions in
  38 the same relative paths below
  39 .Ar dstdir .
  40 Subdirectories of
  41 .Ar dstdir
  42 are created as needed.
  43 Existing files are not explicitly deleted, but possibly overwritten.
  44 .Pp
  45 The options are as follows:
  46 .Bl -tag -width Ds
  47 .It Fl I Cm os Ns = Ns Ar name
  48 Override the default operating system
  49 .Ar name
  50 for the
  51 .Xr mdoc 7
  52 .Ic \&Os
  53 and for the
  54 .Xr man 7
  55 .Ic TH
  56 macro.
  57 .It Fl T Ar output
  58 Output format.
  59 The
  60 .Ar output
  61 argument can be
  62 .Cm ascii ,
  63 .Cm utf8 ,
  64 or
  65 .Cm html ;
  66 see
  67 .Xr mandoc 1 .
  68 In
  69 .Cm html
  70 output mode, the
  71 .Cm fragment
  72 output option is implied.
  73 Other output options are not supported.
  74 .El
  75 .Sh IMPLEMENTATION NOTES
  76 Since this version avoids
  77 .Xr fork 2
  78 and
  79 .Xr exec 3
  80 overhead and uses the much faster
  81 .Sy mandoc
  82 parsers and formatters rather than
  83 .Sy groff ,
  84 it may be about one order of magnitude faster than other
  85 .Nm
  86 implementations.
  87 .Sh EXIT STATUS
  88 .Ex -std
  89 .Pp
  90 Possible errors include:
  91 .Bl -bullet
  92 .It
  93 missing, invalid, or excessive command line arguments
  94 .It
  95 failure to change the current working directory to
  96 .Ar srcdir
  97 .It
  98 failure to open
  99 .Ar dstdir
 100 .It
 101 communication failure with
 102 .Xr mandocd 8
 103 .It
 104 resource exhaustion, for example file descriptor, process table,
 105 or memory exhaustion
 106 .El
 107 .Pp
 108 Except for memory exhaustion and similar system-level failures,
 109 failures while trying to open, read, parse, or format individual
 110 manual pages, to save individual formatted files to the file system,
 111 or even to create directories do not cause
 112 .Nm
 113 to return an error exit status.
 114 In such cases,
 115 .Nm
 116 will simply continue with the next file or subdirectory.
 117 .Sh SEE ALSO
 118 .Xr mandoc 1 ,
 119 .Xr mandocd 8
 120 .Sh HISTORY
 121 A
 122 .Nm
 123 utility first appeared in
 124 .Fx 1.0 .
 125 Other, incompatible implementations appeared in
 126 .Nx 1.0
 127 and in
 128 .Sy man-db No 2.2 .
 129 .Pp
 130 This version appeared in version 1.14.1 of the
 131 .Sy mandoc
 132 toolkit.
 133 .Sh AUTHORS
 134 .An -nosplit
 135 The first
 136 .Nm
 137 implementation was a short shell script by
 138 .An Christoph Robitschko
 139 in July 1993.
 140 .Pp
 141 The
 142 .Nx
 143 implementations were written by
 144 .An J. T. Conklin Aq Mt jtc@netbsd.org
 145 in 1993,
 146 .An Christian E. Hopps Aq Mt chopps@netbsd.org
 147 in 1994,
 148 and
 149 .An Dante Profeta Aq Mt dante@netbsd.org
 150 in 1999; the
 151 .Sy man-db
 152 implementation by
 153 .An Graeme W. Wilford
 154 in 1994; and the
 155 .Fx
 156 implementations by
 157 .An Wolfram Schneider Aq Mt wosch@freebsd.org
 158 in 1995 and
 159 .An John Rochester Aq Mt john@jrochester.org
 160 in 2002.
 161 .Pp
 162 The concept of the present version was designed and implemented by
 163 .An Michael Stapelberg Aq Mt stapelberg@debian.org
 164 in 2017.
 165 Option and argument handling and directory iteration was added by
 166 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
 167 .Sh CAVEATS
 168 All versions of
 169 .Nm
 170 are incompatible with each other because each caters to the needs
 171 of a specific operating system, for example regarding directory
 172 structures and file naming conventions.
 173 .Pp
 174 This version is more flexible than the others in so far as it does
 175 not assume any particular directory structure or naming convention.
 176 That flexibility comes at the price of not being able to change the
 177 names and relative paths of the source files when reusing them to
 178 store the formatted files, of not supporting any configuration file
 179 formats or environment variables, and of being unable to scan for
 180 and remove junk files in
 181 .Ar dstdir .
 182 .Pp
 183 Currently,
 184 .Nm
 185 always reformats each page, even if the formatted version is newer
 186 than the source version.