Annotation of mandoc/catman.8, Revision 1.7
1.7 ! schwarze 1: .\" $Id$
1.1 kristaps 2: .\"
1.7 ! schwarze 3: .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
1.1 kristaps 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: .\"
1.7 ! schwarze 17: .Dd $Mdocdate$
1.1 kristaps 18: .Dt CATMAN 8
19: .Os
20: .Sh NAME
21: .Nm catman
1.7 ! schwarze 22: .Nd format all manual pages below a directory
1.1 kristaps 23: .Sh SYNOPSIS
24: .Nm catman
1.7 ! schwarze 25: .Op Fl I Cm os Ns = Ns Ar name
! 26: .Op Fl T Ar output
! 27: .Ar srcdir dstdir
1.1 kristaps 28: .Sh DESCRIPTION
29: The
30: .Nm
1.7 ! schwarze 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.
1.5 kristaps 44: .Pp
1.7 ! schwarze 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
1.5 kristaps 85: .Nm
1.7 ! schwarze 86: implementations.
! 87: .Sh EXIT STATUS
! 88: .Ex -std
1.5 kristaps 89: .Pp
1.7 ! schwarze 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
1.1 kristaps 106: .El
107: .Pp
1.7 ! schwarze 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.
1.1 kristaps 117: .Sh SEE ALSO
118: .Xr mandoc 1 ,
1.7 ! schwarze 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.
1.1 kristaps 133: .Sh AUTHORS
1.7 ! schwarze 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
1.1 kristaps 141: The
1.7 ! schwarze 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,
1.1 kristaps 184: .Nm
1.7 ! schwarze 185: always reformats each page, even if the formatted version is newer
! 186: than the source version.
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to catman.8 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc