Annotation of mandoc/catman.8, Revision 1.9
1.9 ! schwarze 1: .\" $Id: catman.8,v 1.8 2017/03/18 19:56:01 schwarze Exp $
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.9 ! schwarze 17: .Dd $Mdocdate: March 18 2017 $
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
1.8 schwarze 52: .Ic \&Os
1.7 schwarze 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.9 ! schwarze 90: Failures while trying to open individual manual pages for reading,
! 91: to save individual formatted files to the file system,
! 92: or even to read or create subdirectories do not cause
! 93: .Nm
! 94: to return an error exit status.
! 95: In such cases,
! 96: .Nm
! 97: simply continues with the next file or subdirectory.
! 98: .Sh DIAGNOSTICS
! 99: Some fatal errors cause
! 100: .Nm
! 101: to exit before the iteration over input files is even started:
! 102: .Bl -tag -width Ds -offset indent
! 103: .It unknown option \-\- Ar option
! 104: An invalid option was passed on the command line.
! 105: .It Sy socketpair : Ar reason
! 106: The sockets needed for communication with
! 107: .Xr mandocd 8
! 108: could not be created, for example due to file descriptor or memory exhaustion.
! 109: .It Sy fork : Ar reason
! 110: The new process needed to run
! 111: .Xr mandocd 8
! 112: could not be created, for example due to process table exhaustion
! 113: or system resource limits.
! 114: .It Sy exec Ns Po Sy mandocd Pc : Ar reason
! 115: The
! 116: .Xr mandocd 8
! 117: child program could not be started, for example because it is not in the
! 118: .Ev PATH
! 119: or has no execute permission.
! 120: .It Sy open No destination Ar dstdir : reason
! 121: The
! 122: .Ar dstdir
! 123: could not be opened for reading, for example because it does not exist,
! 124: it is not a directory, or permission is denied.
! 125: .It Sy chdir No to source Ar srcdir : reason
! 126: The current working directory could not be changed to
! 127: .Ar srcdir ,
! 128: for example because it does not exist, it is not a directory,
! 129: or permission is denied.
! 130: .It Sy fts_open : Ar reason
! 131: Starting the iteration was attempted, but failed.
! 132: .El
! 133: .Pp
! 134: Some fatal errors cause the iteration over input files to be aborted
! 135: prematurely:
! 136: .Bl -tag -width Ds -offset indent
! 137: .It FATAL: Sy fts_read : Ar reason
! 138: A call to
! 139: .Xr fts_read 3
! 140: returned
! 141: .Dv NULL ,
! 142: meaning that the iteration failed before being complete.
! 143: .It FATAL: Sy sendmsg : Ar reason
! 144: The file descriptors needed to process one of the manual pages
! 145: could not be sent to
! 146: .Xr mandocd 8 ,
! 147: for example because
! 148: .Xr mandocd 8
! 149: could not be started or died unexpectedly.
! 150: .El
! 151: .Pp
! 152: Some non-fatal errors cause a single subdirectory to be skipped.
! 153: The iteration is not aborted but continues with the next subdirectory,
! 154: and the exit status is unaffected:
! 155: .Bl -tag -width Ds -offset indent
! 156: .It directory Ar subdirectory No unreadable : Ar reason
! 157: A directory below
! 158: .Ar srcdir
! 159: could not be read and is skipped.
! 160: .It directory Ar subdirectory No causes cycle
! 161: A directory below
! 162: .Ar srcdir
! 163: is skipped because it would cause cyclic processing.
! 164: .It Sy mkdirat Ar subdirectory : reason
! 165: A required directory below
! 166: .Ar dstdir
! 167: does not exist and could not be created.
! 168: The corresponding subdirectory below
! 169: .Ar srcdir
! 170: is skipped.
! 171: .El
! 172: .Pp
! 173: Some non-fatal errors cause a single source file to be skipped.
! 174: The iteration is not aborted but continues with the next file,
! 175: and the exit status is unaffected:
! 176: .Pp
! 177: .Bl -tag -width Ds -offset indent
! 178: .It file Ar filename : reason
! 179: The function
! 180: .Xr fts_read 3
! 181: reported a non-fatal error with respect to
! 182: .Ar filename .
! 183: .It Ar filname : No not a regular file
! 184: For example, it might be a symbolic link or a device file.
! 185: .It Sy open Ar filename No for reading : Ar reason
! 186: A file below
1.7 schwarze 187: .Ar srcdir
1.9 ! schwarze 188: could not be read, for example due to permission problems.
! 189: .It Sy openat Ar filename No for writing : Ar reason
! 190: A file below
1.7 schwarze 191: .Ar dstdir
1.9 ! schwarze 192: could not be created or truncated, for example due to permission problems.
1.1 kristaps 193: .El
194: .Pp
1.9 ! schwarze 195: If errors occur, the applicable summary messages appear
! 196: after the end of the iteration:
! 197: .Pp
! 198: .Bl -tag -width Ds -offset indent -compact
! 199: .It skipped Ar number No directories due to errors
! 200: .It skipped Ar number No files due to errors
! 201: .It processing aborted due to fatal error
! 202: .El
1.1 kristaps 203: .Sh SEE ALSO
204: .Xr mandoc 1 ,
1.7 schwarze 205: .Xr mandocd 8
206: .Sh HISTORY
207: A
208: .Nm
209: utility first appeared in
210: .Fx 1.0 .
211: Other, incompatible implementations appeared in
212: .Nx 1.0
213: and in
214: .Sy man-db No 2.2 .
215: .Pp
216: This version appeared in version 1.14.1 of the
217: .Sy mandoc
218: toolkit.
1.1 kristaps 219: .Sh AUTHORS
1.7 schwarze 220: .An -nosplit
221: The first
222: .Nm
223: implementation was a short shell script by
224: .An Christoph Robitschko
225: in July 1993.
226: .Pp
1.1 kristaps 227: The
1.7 schwarze 228: .Nx
229: implementations were written by
230: .An J. T. Conklin Aq Mt jtc@netbsd.org
231: in 1993,
232: .An Christian E. Hopps Aq Mt chopps@netbsd.org
233: in 1994,
234: and
235: .An Dante Profeta Aq Mt dante@netbsd.org
236: in 1999; the
237: .Sy man-db
238: implementation by
239: .An Graeme W. Wilford
240: in 1994; and the
241: .Fx
242: implementations by
243: .An Wolfram Schneider Aq Mt wosch@freebsd.org
244: in 1995 and
245: .An John Rochester Aq Mt john@jrochester.org
246: in 2002.
247: .Pp
248: The concept of the present version was designed and implemented by
249: .An Michael Stapelberg Aq Mt stapelberg@debian.org
250: in 2017.
251: Option and argument handling and directory iteration was added by
252: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
253: .Sh CAVEATS
254: All versions of
255: .Nm
256: are incompatible with each other because each caters to the needs
257: of a specific operating system, for example regarding directory
258: structures and file naming conventions.
259: .Pp
260: This version is more flexible than the others in so far as it does
261: not assume any particular directory structure or naming convention.
262: That flexibility comes at the price of not being able to change the
263: names and relative paths of the source files when reusing them to
264: store the formatted files, of not supporting any configuration file
265: formats or environment variables, and of being unable to scan for
266: and remove junk files in
267: .Ar dstdir .
268: .Pp
269: Currently,
1.1 kristaps 270: .Nm
1.7 schwarze 271: always reformats each page, even if the formatted version is newer
272: 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