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 29The 30.Nm 31utility assumes that all files below 32.Ar srcdir 33are manual pages in 34.Xr mdoc 7 35and 36.Xr man 7 37format and formats all of them, storing the formatted versions in 38the same relative paths below 39.Ar dstdir . 40Subdirectories of 41.Ar dstdir 42are created as needed. 43Existing files are not explicitly deleted, but possibly overwritten. 44.Pp 45The options are as follows: 46.Bl -tag -width Ds 47.It Fl I Cm os Ns = Ns Ar name 48Override the default operating system 49.Ar name 50for the 51.Xr mdoc 7 52.Ic \&Os 53and for the 54.Xr man 7 55.Ic TH 56macro. 57.It Fl T Ar output 58Output format. 59The 60.Ar output 61argument can be 62.Cm ascii , 63.Cm utf8 , 64or 65.Cm html ; 66see 67.Xr mandoc 1 . 68In 69.Cm html 70output mode, the 71.Cm fragment 72output option is implied. 73Other output options are not supported. 74.El 75.Sh IMPLEMENTATION NOTES 76Since this version avoids 77.Xr fork 2 78and 79.Xr exec 3 80overhead and uses the much faster 81.Sy mandoc 82parsers and formatters rather than 83.Sy groff , 84it may be about one order of magnitude faster than other 85.Nm 86implementations. 87.Sh EXIT STATUS 88.Ex -std 89.Pp 90Possible errors include: 91.Bl -bullet 92.It 93missing, invalid, or excessive command line arguments 94.It 95failure to change the current working directory to 96.Ar srcdir 97.It 98failure to open 99.Ar dstdir 100.It 101communication failure with 102.Xr mandocd 8 103.It 104resource exhaustion, for example file descriptor, process table, 105or memory exhaustion 106.El 107.Pp 108Except for memory exhaustion and similar system-level failures, 109failures while trying to open, read, parse, or format individual 110manual pages, to save individual formatted files to the file system, 111or even to create directories do not cause 112.Nm 113to return an error exit status. 114In such cases, 115.Nm 116will simply continue with the next file or subdirectory. 117.Sh SEE ALSO 118.Xr mandoc 1 , 119.Xr mandocd 8 120.Sh HISTORY 121A 122.Nm 123utility first appeared in 124.Fx 1.0 . 125Other, incompatible implementations appeared in 126.Nx 1.0 127and in 128.Sy man-db No 2.2 . 129.Pp 130This version appeared in version 1.14.1 of the 131.Sy mandoc 132toolkit. 133.Sh AUTHORS 134.An -nosplit 135The first 136.Nm 137implementation was a short shell script by 138.An Christoph Robitschko 139in July 1993. 140.Pp 141The 142.Nx 143implementations were written by 144.An J. T. Conklin Aq Mt jtc@netbsd.org 145in 1993, 146.An Christian E. Hopps Aq Mt chopps@netbsd.org 147in 1994, 148and 149.An Dante Profeta Aq Mt dante@netbsd.org 150in 1999; the 151.Sy man-db 152implementation by 153.An Graeme W. Wilford 154in 1994; and the 155.Fx 156implementations by 157.An Wolfram Schneider Aq Mt wosch@freebsd.org 158in 1995 and 159.An John Rochester Aq Mt john@jrochester.org 160in 2002. 161.Pp 162The concept of the present version was designed and implemented by 163.An Michael Stapelberg Aq Mt stapelberg@debian.org 164in 2017. 165Option and argument handling and directory iteration was added by 166.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 167.Sh CAVEATS 168All versions of 169.Nm 170are incompatible with each other because each caters to the needs 171of a specific operating system, for example regarding directory 172structures and file naming conventions. 173.Pp 174This version is more flexible than the others in so far as it does 175not assume any particular directory structure or naming convention. 176That flexibility comes at the price of not being able to change the 177names and relative paths of the source files when reusing them to 178store the formatted files, of not supporting any configuration file 179formats or environment variables, and of being unable to scan for 180and remove junk files in 181.Ar dstdir . 182.Pp 183Currently, 184.Nm 185always reformats each page, even if the formatted version is newer 186than the source version. 187