feat: Added FreeBSD man pages

1 files changed, 191 insertions, 0 deletions

diff --git a/static/freebsd/man8/debug.sh.8 b/static/freebsd/man8/debug.sh.8
new file mode 100644
index 00000000..3b59d6ae
--- /dev/null
+++ b/static/freebsd/man8/debug.sh.8
@@ -0,0 +1,191 @@
+.\" Copyright (c) 1994-2021 Simon J. Gerraty
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" This file is provided in the hope that it will
+.\" be of use.  There is absolutely NO WARRANTY.
+.\" Permission to copy, redistribute or otherwise
+.\" use this file is hereby granted provided that
+.\" the above copyright notice and this notice are
+.\" left intact.
+.\"
+.\" Please send copies of changes and bug-fixes to:
+.\" sjg@crufty.net
+.\"
+.Dd October 22, 2024
+.Dt DEBUG.SH 8
+.Os
+.Sh NAME
+.Nm debug.sh
+.Nd selectively debug scripts
+.Sh SYNOPSIS
+.Bl -item -compact
+.It
+.Ic $_DEBUG_SH .\& Pa debug.sh
+.Pp
+.It
+.Ic DebugOn Oo Fl eo Oc Ar tag ...
+.It
+.Ic DebugOff Oo Fl eo Oc Oo Cm rc= Ns Ar rc Oc Ar tag ...
+.It
+.Ic Debugging
+.It
+.Ic DebugAdd Ar tag
+.It
+.Ic DebugEcho Op Ar message
+.It
+.Ic DebugLog Op Ar message
+.It
+.Ic DebugShell Ar tag ...
+.It
+.Ic DebugTrace Ar message
+.It
+.Ic Debug Ar tag ...
+.El
+.Sh DESCRIPTION
+.Nm
+provides the following functions to facilitate flexible
+run-time tracing of complicated shell scripts.
+.Bl -tag -width 4n
+.It Ic DebugOn Oo Fl eo Oc Ar tag ...
+turns tracing on if any
+.Ar tag
+is found in
+.Va DEBUG_SH
+(a comma separated list of tags).
+.Pp
+It turns tracing off if
+.Ar !tag
+is found in
+.Va DEBUG_SH .
+.Pp
+It sets
+.Va DEBUG_ON
+to the
+.Ar tag
+that caused tracing to be enabled, or
+.Va DEBUG_OFF
+if we matched
+.Ar !tag .
+.Pp
+If
+.Fl e
+option is present, returns 1 if no
+.Ar tag
+matched.
+.Pp
+If
+.Fl o
+option is present, tracing is turned off unless there
+was a matched
+.Ar tag ,
+useful for functions too noisy to tace.
+.It Ic DebugOff Oo Fl eo Oc Oo Cm rc= Ns Ar rc Oc Ar tag ...
+turns tracing on if any
+.Ar tag
+matches
+.Va DEBUG_OFF
+or off if any
+.Ar tag
+matches
+.Va DEBUG_ON .
+This allows nested functions to not interfere with each other.
+.Pp
+The flags
+.Fl e
+and
+.Fl o
+are ignored, they just allow for symmetry with calls to
+.Fn DebugOn .
+.Pp
+The optional
+.Ar rc
+value will be returned rather than the default of 0.
+Thus if
+.Fn DebugOff
+is the last operation in a function,
+.Ar rc
+will be the return code of the function.
+.It Ic Debugging
+returns true if tracing is enabled.
+It is useful for bounding complex debug actions, rather than
+using lots of
+.Ic $DEBUG_DO
+lines.
+.It Ic DebugAdd Ar tag
+Add
+.Ar tag
+to
+.Va DEBUG_SH
+to influence later output,
+possibly in a child process.
+.It Ic DebugEcho
+is just shorthand for:
+.Bd -literal -offset indent
+$DEBUG_DO echo "$@"
+.Ed
+.It Ic DebugLog Op Ar message
+If debugging is enabled, output
+.Ar message
+prefixed with a time-stamp.
+.It Ic DebugShell Ar tag ...
+runs an interactive shell if any
+.Ar tag
+is found in
+.Va DEBUG_INTERACTIVE ,
+and there is a tty available.
+The shell used is defined by
+.Va DEBUG_SHELL
+or
+.Va SHELL
+and defaults to
+.Pa /bin/sh .
+.It Ic DebugTrace Ar message
+Debug output can be very noisy, and it can be tricky
+to align with the script.
+This function outputs a very noticeable banner indicating the value of
+.Va DEBUG_ON ,
+and
+.Ar message
+is passed to
+.Fn DebugLog ,
+finally the banner is repeated.
+.It Ic Debug Ar tag ...
+For backwards compatibility, calls
+.Fn DebugOn
+and if that does not turn tracing on,
+it calls
+.Fn DebugOff
+to turn it off.
+.El
+.Pp
+The variables
+.Va DEBUG_SKIP
+and
+.Va DEBUG_DO
+are set so as to enable/disable code that should be
+skipped/run when debugging is turned on.
+.Va DEBUGGING
+is the same as
+.Va DEBUG_SKIP
+for backwards compatibility and is only set by
+.Fn Debug .
+.Pp
+The use of
+.Ic $_DEBUG_SH
+is to prevent multiple inclusion,
+though it does no harm in this case.
+.Sh BUGS
+Does not work with some versions of
+.Xr ksh 1 .
+If a function turns tracing on, ksh turns it off when the
+function returns - useless.
+.Pp
+PD ksh works ok ;-)
+.Sh AUTHOR
+.An -nosplit
+.Nm
+was written by
+.An Simon J Gerraty Aq Mt sjg@crufty.net .
+
+