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

Annotation of mandoc/catman.8, Revision 1.8

1.8     ! schwarze    1: .\"    $Id: catman.8,v 1.7 2017/02/06 19:04:21 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.8     ! schwarze   17: .Dd $Mdocdate: February 6 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.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