1 files changed, 374 insertions, 0 deletions
diff --git a/static/freebsd/man8/catman.8 b/static/freebsd/man8/catman.8
new file mode 100644
index 00000000..c0f14872
--- /dev/null
+++ b/static/freebsd/man8/catman.8
@@ -0,0 +1,374 @@
+.\" $Id: catman.8,v 1.15 2025/07/13 14:15:26 schwarze Exp $
+.\"
+.\" Copyright (c) 2017, 2025 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: July 13 2025 $
+.Dt CATMAN 8
+.Os
+.Sh NAME
+.Nm catman
+.Nd format all manual pages below a directory
+.Sh SYNOPSIS
+.Nm catman
+.Op Fl I Cm os Ns = Ns Ar name
+.Op Fl T Ar output
+.Ar srcdir dstdir
+.Sh DESCRIPTION
+The
+.Nm
+utility assumes that all files below
+.Ar srcdir
+are manual pages in
+.Xr mdoc 7
+and
+.Xr man 7
+format and formats all of them, storing the formatted versions in
+the same relative paths below
+.Ar dstdir .
+Unless they already exist,
+.Ar dstdir
+itself and any required subdirectories are created.
+Existing files are not explicitly deleted, but possibly overwritten.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl I Cm os Ns = Ns Ar name
+Override the default operating system
+.Ar name
+for the
+.Xr mdoc 7
+.Ic \&Os
+and for the
+.Xr man 7
+.Ic TH
+macro.
+.It Fl T Ar output
+Output format.
+The
+.Ar output
+argument can be
+.Cm ascii ,
+.Cm utf8 ,
+or
+.Cm html ;
+see
+.Xr mandoc 1 .
+In
+.Cm html
+output mode, the
+.Cm fragment
+output option is implied.
+Other output options are not supported.
+.It Fl v
+Verbose mode, printing additional information to standard error output.
+Specifying this once prints a summary about the number of files
+and directories processed at the end of the iteration.
+Specifying it twice additionally prints debugging information
+about the backchannel from
+.Xr mandocd 8
+to
+.Nm
+that is used to limit the number of files in flight at any given time.
+For details, see
+.Sx DIAGNOSTICS .
+.El
+.Sh IMPLEMENTATION NOTES
+Since this version avoids
+.Xr fork 2
+and
+.Xr exec 3
+overhead and uses the much faster
+.Sy mandoc
+parsers and formatters rather than
+.Sy groff ,
+it may be about one order of magnitude faster than other
+.Nm
+implementations.
+.Sh EXIT STATUS
+.Ex -std
+.Pp
+Failures while trying to open individual manual pages for reading,
+to save individual formatted files to the file system,
+or even to read or create subdirectories do not cause
+.Nm
+to return an error exit status.
+In such cases,
+.Nm
+simply continues with the next file or subdirectory.
+.Sh DIAGNOSTICS
+Some fatal errors cause
+.Nm
+to exit before the iteration over input files is even started:
+.Bl -tag -width Ds -offset indent
+.It unknown option \-\- Ar option
+An invalid option was passed on the command line.
+.It missing arguments: srcdir and dstdir
+No argument was provided.
+Both
+.Ar srcdir
+and
+.Ar dstdir
+are mandatory.
+.It missing argument: dstdir
+Only one argument was provided.
+The second argument,
+.Ar dstdir ,
+is mandatory, too.
+.It too many arguments: Ar third argument
+Three or more arguments were provided, but only two are supported.
+.It Sy socketpair : Ar reason
+The sockets needed for communication with
+.Xr mandocd 8
+could not be created, for example due to file descriptor or memory exhaustion.
+.It Sy fork : Ar reason
+The new process needed to run
+.Xr mandocd 8
+could not be created, for example due to process table exhaustion
+or system resource limits.
+.It Sy exec Ns Po Sy mandocd Pc : Ar reason
+The
+.Xr mandocd 8
+child program could not be started, for example because it is not in the
+.Ev PATH
+or has no execute permission.
+.It Sy mkdir No destination Ar dstdir : reason
+The
+.Ar dstdir
+does not exist and could not be created, for example because
+the parent directory does not exist or permission is denied.
+.It Sy open No destination Ar dstdir : reason
+The
+.Ar dstdir
+could not be opened for reading, for example because
+it is not a directory or permission is denied.
+.It Sy chdir No to source Ar srcdir : reason
+The current working directory could not be changed to
+.Ar srcdir ,
+for example because it does not exist, it is not a directory,
+or permission is denied.
+.It Sy fts_open : Ar reason
+Starting the iteration was attempted but failed,
+for example due to memory exhaustion.
+.El
+.Pp
+Some fatal errors cause the iteration over input files to be aborted
+prematurely:
+.Bl -tag -width Ds -offset indent
+.It FATAL: Sy fts_read : Ar reason
+A call to
+.Xr fts_read 3
+returned
+.Dv NULL ,
+meaning that the iteration failed before being complete.
+.It FATAL: mandocd child died: got Ar SIGNAME
+This message appears if
+.Nm
+gets the
+.Dv SIGCHLD
+or
+.Dv SIGPIPE
+signal, most likely due to a fatal bug in
+.Xr mandocd 8 .
+.It FATAL: Sy sendmsg : Ar reason
+The file descriptors needed to process one of the manual pages
+could not be sent to
+.Xr mandocd 8 ,
+for example because
+.Xr mandocd 8
+could not be started or died unexpectedly.
+.It FATAL: Sy recv : Ar reason
+Trying to read a reply message from
+.Xr mandocd 8
+failed, most likely because
+.Xr mandocd 8
+unexpectedly died or closed the socket.
+.It FATAL: signal Ar SIGNAME
+This message appears if
+.Nm
+gets a
+.Dv SIGHUP ,
+.Dv SIGINT ,
+or
+.Dv SIGTERM
+signal, for example because the user deliberately killed it.
+.El
+.Pp
+Some non-fatal errors cause a single subdirectory to be skipped.
+The iteration is not aborted but continues with the next subdirectory,
+and the exit status is unaffected:
+.Bl -tag -width Ds -offset indent
+.It directory Ar subdirectory No unreadable : Ar reason
+A directory below
+.Ar srcdir
+could not be read and is skipped.
+.It directory Ar subdirectory No causes cycle
+A directory below
+.Ar srcdir
+is skipped because it would cause cyclic processing.
+.It Sy mkdirat Ar subdirectory : reason
+A required directory below
+.Ar dstdir
+does not exist and could not be created.
+The corresponding subdirectory below
+.Ar srcdir
+is skipped.
+.El
+.Pp
+Some non-fatal errors cause a single source file to be skipped.
+The iteration is not aborted but continues with the next file,
+and the exit status is unaffected:
+.Bl -tag -width Ds -offset indent
+.It file Ar filename : reason
+The function
+.Xr fts_read 3
+reported a non-fatal error with respect to
+.Ar filename .
+.It file Ar filename : No not a regular file
+For example, it might be a symbolic link or a device file.
+.It Sy open Ar filename No for reading : Ar reason
+A file below
+.Ar srcdir
+could not be read, for example due to permission problems.
+.It Sy openat Ar filename No for writing : Ar reason
+A file below
+.Ar dstdir
+could not be created or truncated, for example due to permission problems.
+.El
+.Pp
+If errors occur, the applicable summary messages appear
+after the end of the iteration:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It skipped Ar number No directories due to errors
+.It skipped Ar number No files due to errors
+.It processing aborted due to fatal error
+.El
+.Pp
+If the
+.Fl v
+flag is specified, the following summary message also appears:
+.Bl -tag -width Ds -offset indent
+.It processed Ar nfiles No files in Ar ndirs No directories
+A file is counted if it could be opened for reading and the
+corresponding output file could be opened for writing;
+this does not necessarily mean that it is a useful manual page.
+A directory is counted if it could be opened for reading and the
+corresponding output directory existed or could be created;
+this does not necessarily mean that any files could be
+processed inside.
+.El
+.Pp
+If the
+.Fl v
+flag is specified twice, the following messages also appear:
+.Bl -tag -width Ds -offset indent
+.It allowing up to Ar number No files in flight
+This is printed at the beginning of the iteration,
+showing the maximum number of files that
+.Nm
+allows to be in flight at any given time.
+.It files in flight: Ar old No \- Ar decrement No = Ar new
+This message is printed when
+.Nm
+learns about
+.Xr mandocd 8
+accepting more than one file at the same time.
+The three numbers printed are the old number of files in flight,
+the amount this number is being reduced, and the resulting
+new number of files in flight.
+.It waiting for Ar number No files in flight
+This message is printed at the end of the iteration, after
+.Nm
+has submitted all files to
+.Xr mandocd 8
+that it intends to.
+THe message informs about the number of files still in flight
+at this point.
+The
+.Nm
+program then waits until
+.Xr mandocd 8
+has accepted them all or until an error occurs.
+.El
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr mandocd 8
+.Sh HISTORY
+A
+.Nm
+utility first appeared in
+.Fx 1.0 .
+Other, incompatible implementations appeared in
+.Nx 1.0
+and in
+.Sy man-db No 2.2 .
+.Pp
+This version appeared in version 1.14.1 of the
+.Sy mandoc
+toolkit.
+.Sh AUTHORS
+.An -nosplit
+The first
+.Nm
+implementation was a short shell script by
+.An Christoph Robitschko
+in July 1993.
+.Pp
+The
+.Nx
+implementations were written by
+.An J. T. Conklin Aq Mt jtc@netbsd.org
+in 1993,
+.An Christian E. Hopps Aq Mt chopps@netbsd.org
+in 1994,
+and
+.An Dante Profeta Aq Mt dante@netbsd.org
+in 1999; the
+.Sy man-db
+implementation by
+.An Graeme W. Wilford
+in 1994; and the
+.Fx
+implementations by
+.An Wolfram Schneider Aq Mt wosch@freebsd.org
+in 1995 and
+.An John Rochester Aq Mt john@jrochester.org
+in 2002.
+.Pp
+The concept of the present version was designed and implemented by
+.An Michael Stapelberg Aq Mt stapelberg@debian.org
+in 2017.
+Option and argument handling and directory iteration was added by
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
+.Sh CAVEATS
+All versions of
+.Nm
+are incompatible with each other because each caters to the needs
+of a specific operating system, for example regarding directory
+structures and file naming conventions.
+.Pp
+This version is more flexible than the others in so far as it does
+not assume any particular directory structure or naming convention.
+That flexibility comes at the price of not being able to change the
+names and relative paths of the source files when reusing them to
+store the formatted files, of not supporting any configuration file
+formats or environment variables, and of being unable to scan for
+and remove junk files in
+.Ar dstdir .
+.Pp
+Currently,
+.Nm
+always reformats each page, even if the formatted version is newer
+than the source version.