+%%% -*-latex-*-
+%%%
+%%% Miscellaneous functionality
+%%%
+%%% (c) 2015 Straylight/Edgeware
+%%%
+
+%%%----- Licensing notice ---------------------------------------------------
+%%%
+%%% This file is part of the Sensble Object Design, an object system for C.
+%%%
+%%% SOD is free software; you can redistribute it and/or modify
+%%% it under the terms of the GNU General Public License as published by
+%%% the Free Software Foundation; either version 2 of the License, or
+%%% (at your option) any later version.
+%%%
+%%% SOD is distributed in the hope that it will be useful,
+%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
+%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+%%% GNU General Public License for more details.
+%%%
+%%% You should have received a copy of the GNU General Public License
+%%% along with SOD; if not, write to the Free Software Foundation,
+%%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+\chapter{Miscellaneous functionality} \label{ch:misc}
+
+%%%--------------------------------------------------------------------------
+\section{Utilities} \label{sec:misc.utilities}
+
+These symbols are defined in the @|sod-utilities| package.
+
+\begin{describe}{mac}
+ {with-gensyms (@{ @<var> @! (@<var> @[@<name>@]) @}^*) \\ \ind
+ @<body-form>^*}
+\end{describe}
+
+\begin{describe}{mac}
+ {once-only (@[[ :environment @<env> @]]
+ @{ @<var> @! (@<var> @[@<value-form>@]) @}^*) \\ \ind
+ @<body-form>^*}
+\end{describe}
+
+\begin{describe}{mac}
+ {parse-body @<body> @> @<doc-string> @<declarations> @<body-forms>}
+\end{describe}
+
+\begin{describe}{sym}{it}
+\end{describe}
+
+\begin{describe}{mac}{aif @<condition> @<consequent> @[@<alt>@]}
+\end{describe}
+
+\begin{describe}{mac}{awhen @<condition> @<body-form>^*}
+\end{describe}
+
+\begin{describe}{mac}{acond @{ (@<condition> @<form>^*) @}^*}
+\end{describe}
+
+\begin{describe*}
+ {\dhead{mac}
+ {acase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
+ \dhead{mac}
+ {aecase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
+ \dhead{mac}{atypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}
+ \dhead{mac}{aetypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}}
+\end{describe*}
+
+\begin{describe}{mac}{asetf @{ @<place> @<value> @}^*}
+\end{describe}
+
+\begin{describe}{gf}{instance-initargs @<instance>}
+\end{describe}
+
+\begin{describe*}
+ {\dhead{fun}{copy-instance @<instance> \&rest @<initargs>}
+ \dhead{gf}{copy-instance-using-class @<class> @<instance>
+ \&rest @<initargs>}}
+\end{describe*}
+
+\begin{describe*}
+ {\dhead{gf}{generic-function-methods @<generic-function> @> @<list>}
+ \dhead{gf}{method-specializers @<method> @> @<list>}
+ \dhead{cls}{eql-specializer}
+ \dhead{gf}{eql-specializer-object @<specializer> @> @<value>}}
+\end{describe*}
+
+\begin{describe}{fun}{make-list-builder \&optional @<initial> @> @<builder>}
+\end{describe}
+
+\begin{describe}{fun}{lbuild-add @<builder> @<item> @> @<builder>}
+\end{describe}
+
+\begin{describe}{fun}{lbuild-add-list @<builder> @<list> @> @<builder>}
+\end{describe}
+
+\begin{describe}{fun}{lbuild-list @<builder> @> @<list>}
+\end{describe}
+
+\begin{describe}{fun}
+ {mappend @<function> @<list> \&rest @<more-lists> @> @<result-list>}
+\end{describe}
+
+\begin{describe}{cls}{inconsistent-merge-error (error) \&key :candidates}
+\end{describe}
+
+\begin{describe}{gf}{merge-error-candidates @<error> @> @<list>}
+\end{describe}
+
+\begin{describe}{fun}
+ {merge-lists @<lists> \&key :pick (:test \#'eql) @> @<list>}
+\end{describe}
+
+\begin{describe}{mac}
+ {categorize (\=@<item-var> @<items>
+ @[[ :bind (@{ @<var> @! (@<var> @[@<value>@]) @}^*) @]])
+ \\ \ind\ind
+ (@{ @<cat-var> @<cat-predicate> @}^*) \- \\
+ @<body-form>^* \-
+ \nlret @<value>^*}
+\end{describe}
+
+\begin{describe}{fun}
+ {frob-identifier @<string> \&key :swap-case :swap-hyphen
+ @> @<frobbed-string>}
+\end{describe}
+
+\begin{describe}{fun}{whitespace-char-p @<character> @> @<generic-function>}
+\end{describe}
+
+\begin{describe}{fun}
+ {update-position @<character> @<line> @<column>
+ @> @<new-line> @<new-column>}
+\end{describe}
+
+\begin{describe}{fun}
+ {backtrack-position @<character> @<line> @<column>
+ @> @<old-line> @<old-column>}
+\end{describe}
+
+\begin{describe}{fun}
+ {compose @<function> \&rest @<more-functions> @> @<function>}
+\end{describe}
+
+\begin{describe}{fun}{symbolicate \&rest @<symbols> @> @<symbol>}
+\end{describe}
+
+\begin{describe}{mac}
+ {maybe-print-unreadable-object (@<object> @<stream>
+ @[[ :type @<type> @!
+ :identity @<identity> @]]) \\ \ind
+ @<body-form>^*}
+\end{describe}
+
+\begin{describe}{mac}
+ {dosequence (@<var> @<sequence>
+ @[[ :start @<start> @! :end @<end> @!
+ :indexvar @<var> @]]) \\ \ind
+ @{ @<tag> @! @<body-form> @}^*}
+\end{describe}
+
+\begin{describe}{mac}
+ {define-access-wrapper @<from> @<to>
+ @[[ :read-only @<read-only-flag> @]]}
+\end{describe}
+
+\begin{describe}{mac}
+ {default-slot (@<instance> @<slot> @[@<slot-names>@]) \\ \ind
+ @<body-form>^*}
+\end{describe}
+
+\begin{describe}{mac}
+ {define-on-demand-slot @<class> @<slot> (@<instance>) \\ \ind
+ @<body-form>^*}
+\end{describe}
+
+%%%--------------------------------------------------------------------------
+\section{Condition utilities} \label{sec:misc.condition}
+
+These symbols are defined in the @|sod-parser| package.
+
+\begin{describe}{cls}{enclosing-condition (condition) \&key :condition}
+\end{describe}
+
+\begin{describe}{gf}
+ {enclosed-condition @<enclosing-condition> @> @<condition>}
+\end{describe}
+
+\begin{describe}{fun}{cerror* @<datum> \&rest @<arguments>}
+\end{describe}
+
+%%%--------------------------------------------------------------------------
+\section{Option parser} \label{sec:misc.optparse}
+
+These symbols are defined in the @!optparse| package.
+
+\begin{describe}{fun}{exit \&optional (@<code> 0) \&key :abrupt}
+\end{describe}
+
+\begin{describe}{var}{*program-name*}
+\end{describe}
+
+\begin{describe}{var}{*command-line*}
+\end{describe}
+
+\begin{describe}{fun}{set-command-line-arguments}
+\end{describe}
+
+\begin{describe}{cls}{loc}
+\end{describe}
+
+\begin{describe}{fun}{locp @<object> @> @<generalized-boolean>}
+\end{describe}
+
+\begin{describe}{macro}{locf @<place> @> @<locative>}
+\end{describe}
+
+\begin{describe*}
+ {\dhead{fun}{ref @<locative> @> @<value>}
+ \dhead{fun}{setf (ref @<locative>) @<value>}}
+\end{describe*}
+
+\begin{describe}{mac}
+ {with-locatives
+ @{ @<var> @! (@{ @<var> @!
+ (@<var> @[@<locative>@]) @}^*) @} \\ \ind
+ @<body-form>^*}
+\end{describe}
+
+\begin{describe}{fun}{moan @<format-string> \&rest @<format-args>}
+\end{describe}
+
+\begin{describe}{fun}{die @<format-string> \&rest @<format-args>}
+\end{describe}
+
+\begin{describe}{var}{*options*}
+\end{describe}
+
+\begin{describe}{cls}{option}
+\end{describe}
+
+\begin{describe}{fun}{optionp @<object> @> @<generalized-boolean>}
+\end{describe}
+
+\begin{describe}{fun}
+ {make-option \=@<long-name> @<short-name> \+ \\
+ \&optional @<arg-name> \\
+ \&key :tag :negated-tag :arg-optional-p :documentation \-
+ \nlret @<option>}
+\end{describe}
+
+\begin{describe*}
+ {\dhead{fun}{opt-short-name @<option> @> @<character-or-null>}
+ \dhead{fun}{setf (opt-short-name @<option>) @<character-or-null>}
+ \dhead{fun}{opt-long-name @<option> @> @<string-or-null>}
+ \dhead{fun}{setf (opt-long-name @<option>) @<string-or-null>}
+ \dhead{fun}{opt-tag @<option> @> @<tag>}
+ \dhead{fun}{setf (opt-tag @<option>) @<tag>}
+ \dhead{fun}{opt-negated-tag @<option> @> @<tag>}
+ \dhead{fun}{setf (opt-negated-tag @<option>) @<tag>}
+ \dhead{fun}{opt-arg-name @<option> @> @<string-or-null>}
+ \dhead{fun}{setf (opt-arg-name @<option>) @<string-or-null>}
+ \dhead{fun}{opt-optional-p @<option> @> @<generalized-boolean>}
+ \dhead{fun}{setf (opt-optional-p @<option>) @<generalized-boolean>}
+ \dhead{fun}{opt-documentation @<option> @> @<string-or-null>}
+ \dhead{fun}{setf (opt-documentation @<option>) @<string-or-null>}}
+\end{describe*}
+
+\begin{describe}{cls}{option-parser}
+\end{describe}
+
+\begin{describe}{fun}{option-parser-p @<object> @> @<generalized-boolean>}
+\end{describe}
+
+\begin{describe}{fun}
+ {make-option-parser \&key \=:args :options :non-option :numericp \+ \\
+ :negated-numeric-p long-only-p \-
+ \nlret @<option-parser>}
+\end{describe}
+
+\begin{describe*}
+ {\dhead{fun}{op-options @<option-parser> @> @<list>}
+ \dhead{fun}{setf (op-options @<option-parser>) @<list>}
+ \dhead{fun}{op-non-option @<option-parser> @> @<action>}
+ \dhead{fun}{setf (op-non-option @<option-parser>) @<action>}
+ \dhead{fun}{op-long-only-p @<option-parser> @> @<generalized-boolean>}
+ \dhead{fun}{setf (op-long-only-p @<option-parser>) @<generalized-boolean>}
+ \dhead{fun}{op-numeric-p @<option-parser> @> @<generalized-boolean>}
+ \dhead{fun}{setf (op-numeric-p @<option-parser>) @<generalized-boolean>}
+ \dhead{fun}{op-negated-numeric-p @<option-parser> @<generalized-boolean>}
+ \dhead{fun}{setf (op-negated-numeric-p @<option-parser>) @<generalized-boolean>}
+ \dhead{fun}{op-negated-p @<option-parser> @> @<generalized-boolean>}
+ \dhead{fun}{setf (op-negated-p @<option-parser>) @<generalized-boolean>}}
+\end{describe*}
+
+\begin{describe}{cls}
+ {option-parse-error (error simple-condition)
+ \&key :format-control :format-arguments}
+\end{describe}
+
+\begin{describe}{fun}{option-parse-remainder @<option-parser>}
+\end{describe}
+
+\begin{describe}{fun}{option-parse-return @<tag> \&optional @<argument>}
+\end{describe}
+
+\begin{describe}{fun}{option-parse-next @<option-parser>}
+\end{describe}
+
+\begin{describe}{mac}{option-parse-try @<body-form>^*}
+\end{describe}
+
+\begin{describe}{mac}{with-unix-error-reporting () @<body-form>^*}
+\end{describe}
+
+\begin{describe}{mac}
+ {defopthandler @<name> (@<var> @[@<arg>@]) @<lambda-list> \\ \ind
+ @<body-form>^*}
+\end{describe}
+
+\begin{describe}{fun}
+ {invoke-option-handler @<handler> @<locative> @<arg> @<arguments>}
+\end{describe}
+
+\begin{describe}{opt}{set \&optional @<value>}
+\end{describe}
+
+\begin{describe}{opt}{clear \&optional @<value>}
+\end{describe}
+
+\begin{describe}{opt}{inc \&optional @<maximum> @<step>}
+\end{describe}
+
+\begin{describe}{opt}{dec \&optional <minimum> <step>}
+\end{describe}
+
+\begin{describe}{opt}{read}
+\end{describe}
+
+\begin{describe}{opt}{int \&key :radix :min :max}
+\end{describe}
+
+\begin{describe}{opt}{string}
+\end{describe}
+
+\begin{describe}{opt}{keyword \&optional @<valid>}
+\end{describe}
+
+\begin{describe}{opt}{list \&optional @<handler> \&rest @<handler-args>}
+\end{describe}
+
+\begin{describe}{mac}{defoptmacro @<name> @<lambda-list> @<body-form>^*}
+\end{describe}
+
+\begin{describe}{fun}{parse-option-form @<form>}
+\end{describe}
+
+\begin{describe}{mac}
+ {options @{ \=@<string> @! \+ \\
+ @<option-macro> @! (@<option-macro> @<macro-arg>^*) @! \\
+ (@[[ \=@<character> @! (:short-name @<character>) @! \+ \\
+ @<string>^* @! @<symbol> @! @<rational> @!
+ (:long-name @<string>) @! \\
+ (@<string> @<format-arg>^+) @!
+ (:doc @<string> @<format-arg>^*) @! \\
+ (:opt-arg @<arg-name>) @! \\
+ @<keyword> @! (:tag @<tag>) @!
+ (:negated-tag @<tag>) @! \\
+ @{ (@<handler> @<var> @<handler-arg>^*) @}^* @]]) @}^*}
+\end{describe}
+
+\begin{describe}{fun}
+ {simple-usage @<option-list> \&optional @<mandatory-args> @> @<list>}
+\end{describe}
+
+\begin{describe}{fun}{show-usage @<prog> @<usage> \&optional @<stream>}
+\end{describe}
+
+\begin{describe}{fun}
+ {show-help @<prog> @<usage> @<option-list> \&optional @<stream>}
+\end{describe}
+
+\begin{describe}{fun}{sanity-check-option-list @<option-list>}
+\end{describe}
+
+\begin{describe*}
+ {\dhead{var}{*help*}
+ \dhead{var}{*version*}
+ \dhead{var}{*usage*}}
+\end{describe*}
+
+\begin{describe}{fun}{do-usage \&optional @<stream>}
+\end{describe}
+
+\begin{describe}{fun}{die-usage}
+\end{describe}
+
+\begin{describe}{optmac}
+ {help-options \&key :short-help :short-version :short-usage}
+\end{describe}
+
+\begin{describe}{fun}
+ {define-program \&key \=:program-name \+ \\
+ :help :version :usage :full-usage \\
+ :options}
+\end{describe}
+
+\begin{describe}{mac}
+ {do-options (@[[ :parser @<option-parser> @]]) \\ \ind
+ @{ (@{ @<case> @! (@<case>^*)@} (@[@[@<opt-var>@] @<arg-var>@])
+ @<form>^*) @}^*}
+\end{describe}
+
+%%%--------------------------------------------------------------------------
+\section{Property sets} \label{sec:misc.pset}
+
+%%%--------------------------------------------------------------------------
+\section{Miscellaneous translator features} \label{sec:misc.pset}
+
+\begin{describe}{var}{*sod-version*}
+\end{describe}
+
+\begin{describe}{var}{*debugout-pathname*}
+\end{describe}
+
+\begin{describe}{fun}{test-module @<path> @<reason>}
+\end{describe}
+
+\begin{describe}{fun}{exercise}
+\end{describe}
+
+%%%----- That's all, folks --------------------------------------------------
+
+%%% Local variables:
+%%% mode: LaTeX
+%%% TeX-master: "sod.tex"
+%%% TeX-PDF-mode: t
+%%% End: