summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/underscore
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/underscore
Initial commit
Diffstat (limited to 'macros/latex/contrib/underscore')
-rw-r--r--macros/latex/contrib/underscore/miscdoc.sty115
-rw-r--r--macros/latex/contrib/underscore/underscore.pdfbin0 -> 252691 bytes
-rw-r--r--macros/latex/contrib/underscore/underscore.sty248
-rw-r--r--macros/latex/contrib/underscore/underscore.tex184
4 files changed, 547 insertions, 0 deletions
diff --git a/macros/latex/contrib/underscore/miscdoc.sty b/macros/latex/contrib/underscore/miscdoc.sty
new file mode 100644
index 0000000000..da1f2a5fdb
--- /dev/null
+++ b/macros/latex/contrib/underscore/miscdoc.sty
@@ -0,0 +1,115 @@
+\ProvidesPackage{miscdoc}[2010/01/20 v1.2 documentation macros misc latex pkgs]
+
+% miscdoc.sty
+% Copyright 2010 Robin Fairbairns
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Robin Fairbairns.
+%
+% This work consists of the file miscdoc.sty (only)
+
+\setcounter{errorcontextlines}{1274}
+
+% The package arose from a small exercise to document packages whose
+% previous documentation consisted solely of comments in the package files.
+% The macros here defined are lifted from the author's faq.sty
+% (written for the UK TeX FAQ, CTAN:help/uk-tex-faq) or are inspired
+% by others' work (credited where the author is known) ... except
+% where they came as a flash of inspiration while actually writing the
+% documentation.
+
+% this option suggested by Heiko Oberdiek, 2010-01-29
+\DeclareOption{hyper}{%
+ \AtEndOfPackage{%
+ \RequirePackage[pdfusetitle]{hyperref}
+ \RequirePackage{bookmark}
+ \bookmarksetup{numbered,open,openlevel=1}
+ }
+}
+\ProcessOptions\relax
+
+% note: T1 encoding assumed
+\usepackage{lmodern}
+\usepackage[T1]{fontenc}
+\usepackage{booktabs}
+
+% from faq.sty
+\newcommand\cs[1]{\texttt{\char`\\#1}}
+\let\csx\cs
+\def\bsbs{\cs{\char`\\}}
+
+% \cmdinvoke\cs<argument sequence>
+% \cs typeset as above
+% <argument sequence> may consist of optional or mandatory arguments;
+%
+% the `arguments' are simply typesett \texttt, as yet -- if something
+% fancier is needed, there's a bunch of code needs rewriting here...
+\DeclareRobustCommand\cmdinvoke{\@ifstar
+ {\let\@tempa\emph\@scmdinvoke}%
+ {\let\@tempa\relax\@scmdinvoke}%
+}
+\def\@scmdinvoke#1{\texttt{\symbol{92}#1}%
+ \futurelet\@let@token\@cmdinvoke
+}
+\def\@cmdinvoke{\ifx\@let@token\bgroup
+ \let\@tempb\@cmdinvoke@lbrace
+ \else
+ \ifx\@let@token[% ]
+ \let\@tempb\@cmdinvoke@lbrack
+ \else
+ \ifx\@let@token(% )
+ \let\@tempb\@cmdinvoke@lparen
+ \else
+ \let\@tempb\@empty
+ \fi
+ \fi
+ \fi
+ \@tempb
+}
+\def\@cmdinvoke@lbrace#1{\penalty0\hskip0pt\relax
+ \texttt{\symbol{123}\@tempa{#1}\symbol{125}}%
+ \futurelet\@let@token\@cmdinvoke
+}
+\def\@cmdinvoke@lbrack[#1]{\penalty-150\hskip0pt\relax
+ \texttt{[\@tempa{#1}]}%
+ \futurelet\@let@token\@cmdinvoke
+}
+\def\@cmdinvoke@lparen(#1){\penalty-150\hskip0pt\relax
+ \texttt{(\@tempa{#1})}%
+ \futurelet\@let@token\@cmdinvoke
+}
+% and extension -- versions that take a single extra (delimiter)
+% argument, such as \delcmdinvoke{lscrunge}( ... awful syntax, but...
+\DeclareRobustCommand\delcmdinvoke{\@ifstar
+ {\let\@tempa\emph\@sdelcmdinvoke}%
+ {\let\@tempa\relax\@sdelcmdinvoke}%
+}
+\def\@sdelcmdinvoke#1#2{\texttt{\symbol{92}#1#2}%
+ \futurelet\@let@token\@cmdinvoke
+}
+
+% sui generis
+\newcommand\newitem{\par\addvspace{1ex}\noindent}
+
+% inspired by doc.sty in latex distribution
+\newcommand\meta[1]{\ensuremath{\langle}\emph{#1}\ensuremath{\rangle}}
+
+% meaningful names, as in faq.sty
+\newcommand\environment[1]{\texttt{#1}}
+\newcommand\pkgoption[1]{\texttt{#1}}
+\newcommand\extension[1]{\texttt{.#1}}
+\newcommand\Package[1]{\textsf{#1}}
+\def\option{\@ifnextchar[\@optionb\@option}% ]
+\def\@optionb[#1]{{\normalfont\ttfamily[#1]}}
+\def\@option#1{\texttt{#1}}
+
+\let\FontName\textsf \ No newline at end of file
diff --git a/macros/latex/contrib/underscore/underscore.pdf b/macros/latex/contrib/underscore/underscore.pdf
new file mode 100644
index 0000000000..74da138d5d
--- /dev/null
+++ b/macros/latex/contrib/underscore/underscore.pdf
Binary files differ
diff --git a/macros/latex/contrib/underscore/underscore.sty b/macros/latex/contrib/underscore/underscore.sty
new file mode 100644
index 0000000000..f0cfb895d1
--- /dev/null
+++ b/macros/latex/contrib/underscore/underscore.sty
@@ -0,0 +1,248 @@
+% underscore.sty 21-Sep-2005 Donald Arseneau asnd@triumf.ca
+% Make the "_" character print as "\textunderscore" in text.
+% Copyright 1998,2001,2005,2006 Donald Arseneau;
+% License: LPPL version 1.2 or later.
+% Instructions follow after the definitions.
+
+\ProvidesPackage{underscore}[2006/09/13]
+
+\begingroup
+ \catcode`\_=\active
+ \gdef _{% \relax % No relax gives a small vulnerability in alignments
+ \ifx\if@safe@actives\iftrue % must be outermost test!
+ \string_%
+ \else
+ \ifx\protect\@typeset@protect
+ \ifmmode \sb \else \BreakableUnderscore \fi
+ \else
+ \ifx\protect\@unexpandable@protect \noexpand_%
+ \else \protect_%
+ \fi\fi
+ \fi}
+ \global\let\ActiveUnderscore=_
+ \gdef\normalUnderscoreDef{\let_\ActiveUnderscore}
+\endgroup
+
+% At begin: set catcode; fix \long \ttdefault so I can use it in comparisons;
+% reapply definition of active _ in output routine (\@firstofone to strip
+% away braces, so avoiding deeper nesting).
+\AtBeginDocument{%
+ {\immediate\write\@auxout{\catcode\number\string`\_ \string\active}}%
+ \catcode\string`\_\string=\active
+ \edef\ttdefault{\ttdefault}%
+ \output=\expandafter\expandafter\expandafter
+ {\expandafter\expandafter\expandafter\normalUnderscoreDef
+ \expandafter\@firstofone\the\output}%
+}
+
+\newcommand{\BreakableUnderscore}{\leavevmode\nobreak\hskip\z@skip
+ \ifx\f@family\ttdefault \string_\else \textunderscore\fi
+ \usc@dischyph\nobreak\hskip\z@skip}
+
+\DeclareRobustCommand{\_}{%
+ \ifmmode \nfss@text{\textunderscore}\else \BreakableUnderscore \fi}
+
+
+\let\usc@dischyph\@dischyph
+\DeclareOption{nohyphen}{\def\usc@dischyph{\discretionary{}{}{}}}
+\DeclareOption{strings}{\catcode`\_=\active}
+
+\ProcessOptions
+\ifnum\catcode`\_=\active\else \endinput \fi
+
+%%%%%%%% Redefine commands that use character strings %%%%%%%%
+
+\@ifundefined{UnderscoreCommands}{\let\UnderscoreCommands\@empty}{}
+\expandafter\def\expandafter\UnderscoreCommands\expandafter{%
+ \UnderscoreCommands
+ \do\include \do\includeonly
+ \do\@input \do\@iinput \do\InputIfFileExists
+ \do\ref \do\pageref \do\newlabel
+ \do\bibitem \do\@bibitem \do\cite \do\nocite \do\bibcite
+ \do\Ginclude@graphics \do\@setckpt
+}
+
+% Macro to redefine a macro to pre-process its string argument
+% with \protect -> \string.
+\def\do#1{% Avoid double processing if user includes command twice!
+ \@ifundefined{US\string_\expandafter\@gobble\string#1}{%
+ \edef\@tempb{\meaning#1}% Check if macro is just a protection shell...
+ \def\@tempc{\protect}%
+ \edef\@tempc{\meaning\@tempc\string#1\space\space}%
+ \ifx\@tempb\@tempc % just a shell: hook into the protected inner command
+ \expandafter\do
+ \csname \expandafter\@gobble\string#1 \expandafter\endcsname
+ \else % Check if macro takes an optional argument
+ \def\@tempc{\@ifnextchar[}%
+ \edef\@tempa{\def\noexpand\@tempa####1\meaning\@tempc}%
+ \@tempa##2##3\@tempa{##2\relax}%
+ \edef\@tempb{\meaning#1\meaning\@tempc}%
+ \edef\@tempc{\noexpand\@tempd \csname
+ US\string_\expandafter\@gobble\string#1\endcsname}%
+ \if \expandafter\@tempa\@tempb \relax 12\@tempa % then no optional arg
+ \@tempc #1\US@prot
+ \else % There is optional arg
+ \@tempc #1\US@protopt
+ \fi
+ \fi
+ }{}}
+
+\def\@tempd#1#2#3{\let#1#2\def#2{#3#1}}
+
+\def\US@prot#1#2{\let\@@protect\protect \let\protect\string
+ \edef\US@temp##1{##1{#2}}\restore@protect\US@temp#1}
+\def\US@protopt#1{\@ifnextchar[{\US@protarg#1}{\US@prot#1}}
+\def\US@protarg #1[#2]{\US@prot{{#1[#2]}}}
+
+\UnderscoreCommands
+\let\do\relax \let\@tempd\relax % un-do
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\endinput
+
+underscore.sty 13-Sep-2006 Donald Arseneau
+
+Features:
+~~~~~~~~~
+The "\_" command (which normally prints an underscore character or
+facsimile) is altered so that the hyphenation of constituent words
+is not affected, and hyphenation is permitted after the underscore.
+For example, "compound\_fracture" hyphenates as com- pound\_- frac- ture.
+If you prefer the underscore to break without a hyphen (but still with
+the same rules for explicit hyphen-breaks) then use the [nohyphen]
+package option.
+
+A simple "_" acts just like "\_" in text mode, but makes a subscript
+in math mode: activation_energy $E_a$
+
+Both forms use an underscore character if the font encoding contains
+one (e.g., "\usepackage[T1]{fontenc}" or typewriter fonts in any encoding),
+but they use a rule if there is no proper character.
+
+Deficiencies:
+~~~~~~~~~~~~~
+The skips and penalties ruin any kerning with the underscore character
+(when a character is used). However, there doesn't seem to be much, if
+any, such kerning in the ec fonts, and there is never any kerning with
+a rule.
+
+You must avoid "_" in file names and in cite or ref tags, or you must use
+the babel package, with its active-character controls, or you must give
+the [strings] option, which attempts to redefine several commands (and
+may not work perfectly). Even without the [strings] option or babel, you
+can use occasional underscores like: "\include{file\string_name}".
+
+Option: [strings]
+~~~~~~~~~~~~~~~~~
+The default operation is quite simple and needs no customization; but
+you must avoid using "_" in any place where LaTeX uses an argument as
+a string of characters for some control function or as a name. These
+include the tags for "\cite" and "\ref", file names for "\input",
+"\include", and "\includegraphics", environment names, counter names,
+and placement parameters (like "[t]"). The problem with these contexts
+is that they are `moving arguments' but LaTeX does not `switch on' the
+"\protect" mechanism for them.
+
+If you need to use the underscore character in these places, the package
+option [strings] is provided to redefine commands that take such a string
+argument so that protection is applied (with "\protect" being "\string").
+The list of commands is given in "\UnderscoreCommands", with "\do" before
+each; plus several others covering "\input", "\includegraphics, "\cite",
+"\ref", and their variants. Not included are many commands regarding font
+names, everything with counter names, environment names, page styles, and
+versions of "\ref" and "\cite" defined by external packages (e.g., "\vref"
+and "\citeyear").
+
+You can add to the list of supported commands by defining "\UnderscoreCommands"
+before loading this package; e.g.
+
+ \usepackage{chicago}
+ \newcommand{\UnderscoreCommands}{% (\cite already done)
+ \do\citeNP \do\citeA \do\citeANP \do\citeN \do\shortcite
+ \do\shortciteNP \do\shortciteA \do\shortciteANP \do\shortciteN
+ \do\citeyear \do\citeyearNP
+ }
+ \usepackage[strings]{underscore}
+
+Not all commands can be supported this way! Only commands that take a
+string argument *first* can be protected. One optional argument before
+the string argument is also permitted, as exemplified by "\cite": both
+"\cite{tags}" and "\cite[text]{tags}" are allowed. A command like
+"\@addtoreset" which takes two counter names as arguments could not
+be protected by listing it in "\UnderscoreCommands".
+
+*When you use the [strings] option, you must load this package
+last* (or nearly last).
+
+There are two reasons: 1) The redefinitions done for protection must come
+after other packages define their customized versions of those commands.
+2) The [strings] option requires the "_" character to be activated immediately
+in order for the cite and ref tags to be read properly from the .aux file
+as plain strings, and this catcode setting might disrupt other packages.
+
+The babel package implements a protection mechanism for many commands,
+and will be a complete fix for most documents without the [strings] option.
+Many add-on packages are compatible with babel, so they will get the
+strings protection also. However, there are several commands that are
+not covered by babel, but can easily be supported by the [strings] and
+"\UnderscoreCommands" mechanism. Beware that using both [strings] and
+babel might lead to conflicts, but none are seen yet (load babel last).
+
+Implementation Notes:
+~~~~~~~~~~~~~~~~~~~~~
+The first setting of "_" to be an active character is performed in a local
+group so as to not interfere with other packages. The catcode setting
+is repeated with "\AtBeginDocument" so the definition is in effect for the
+text. However, the catcode setting is repeated immediately when the
+[strings] option is detected.
+
+The definition of the active "_" is essentially:
+
+ \ifmmode \sb \else \BreakableUnderscore \fi
+
+where "\sb" retains the normal subscript meaning of "_" and where
+"\BreakableUnderscore" is essentially "\_". The rest of the definition
+handles the "\protect"ion without causing "\relax" to be inserted before
+the character.
+
+"\BreakableUnderscore" uses "\nobreak\hskip\z@skip" to separate the
+underscore from surrounding words, thus allowing TeX to hyphenate them,
+but preventing free breaks around the underscore. Next, it checks the
+current font family, and uses the underscore character from tt fonts or
+otherwise "\textunderscore" (which is a character or rule depending on
+the font encoding). After the underscore, it inserts a discretionary
+hyphenation point as "\usc@dischyph", which is usually just "\-"
+except that it still works in the tabbing environment, although it
+will give "\discretionary{}{}{}" under the [nohyphen] option. After
+that, another piece of non-breaking interword glue is inserted.
+Ordinarily, the comparison "\ifx\f@family\ttdefault" will always fail
+because "\ttdefault" is `long' whereas "\f@family" is not (boooo hisss),
+but "\ttdefault" is redefined to be non-long by "\AtBeginDocument".
+
+The "\_" command is then defined to use "\BreakableUnderscore".
+
+If the [strings] option is not given, then that is all!
+
+Under the [strings] option, the list of special commands is processed to:
+
+ - retain the original command as "\US_"*command* (e.g., "\US_ref")
+ - redefine the command as "\US@prot\US_command" for ordinary commands
+ ("\US@prot\US_ref") or as "\US@protopt\US_command" when an optional
+ argument is possible (e.g., "\US@protopt\US_bibitem").
+ - self-protecting commands ("\cite") retain their self-protection.
+
+Diagnosing the state of the pre-existing command is done by painful
+contortions involving "\meaning".
+
+"\US@prot" and "\US@protopt" read the argument, process it with
+"\protect" enabled, then invoke the saved "\US_command".
+
+Modifications:
+~~~~~~~~~~~~~~
+13-Sep-2006 Reassert my definition in the output routine (listings).
+21-Sep-2005 \includegraphics safe.
+12-Oct-2001 Babel (safe@actives) compatibility and [nohyphen] option.
+
+Test file integrity: ASCII 32-57, 58-126: !"#$%&'()*+,-./0123456789
+:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
diff --git a/macros/latex/contrib/underscore/underscore.tex b/macros/latex/contrib/underscore/underscore.tex
new file mode 100644
index 0000000000..27331aba45
--- /dev/null
+++ b/macros/latex/contrib/underscore/underscore.tex
@@ -0,0 +1,184 @@
+\documentclass[a4paper]{article}
+\usepackage[a4paper]{geometry}
+\usepackage{miscdoc}
+\usepackage[scaled=0.85]{luximono}
+\usepackage{underscore}
+\begin{document}
+\title{The \Package{underscore} package}
+\author{Donald Arseneau\thanks{Documentation file assembled by Robin
+ Fairbairns}}
+\date{13 September 2006, version 1.0}
+\maketitle
+
+\section*{Features}
+
+The package alters the command \cs{_} (which normally prints
+an underscore character or facsimile) so that the hyphenation of
+constituent words is not affected, and hyphenation is permitted after
+the underscore. For example,
+\begin{quote}
+ \texttt{compound\cs{_}fracture}
+\end{quote}
+hyphenates as
+\begin{quote}
+ \texttt{com- pound\cs{_}- frac- ture}
+\end{quote}
+If you prefer the underscore to break without a hyphen (but still with
+the same rules as for explicit hyphen-breaks) then use the
+\option[nohyphen] package option.
+
+A simple ``\texttt{_}'' acts just like ``\cs{_}'' in text
+mode, but makes a subscript in maths mode, so
+\begin{quote}
+ \ttfamily activation_energy \$E_a\$
+\end{quote}
+is printed as
+\begin{quote}
+ activation_energy $E_a$
+\end{quote}
+
+Both forms use an underscore character if the font encoding contains
+one (e.g., with \cmdinvoke{usepackage}[T1]{fontenc} or typewriter
+fonts in any encoding), but they use a rule if there is no proper
+character (just as unmodified \LaTeX{} does).
+
+\section*{Deficiencies}
+
+The skips and penalties ruin any kerning with the underscore character
+(when a character is used). However, there doesn't seem to be much, if
+any, such kerning in the EC fonts, and there is never any kerning with
+a rule.
+
+You must avoid ``\texttt{_}'' in file names and in cite or ref tags, or you must
+use the \Package{babel} package, with its active-character controls,
+or you must give the \option[strings] option, which attempts to
+redefine several commands (and may not work perfectly). Even without
+the \option[strings] option or \Package{babel}, you can use occasional
+underscores like: ``\cmdinvoke{include}{file\string\string_name}''.
+
+\subsection*{Option \protect\option[strings]}
+
+The default operation is quite simple and needs no customization; but
+you must avoid using ``\texttt{_}'' in any place where LaTeX uses an argument
+as a string of characters for some control function or as a name.
+These include the tags for \cs{cite} and \cs{ref}, file names for \cs{input},
+\cs{include}, and \cs{includegraphics}, environment names, counter names,
+and placement parameters (like \option[t]). The problem with these contexts
+is that they are `moving arguments' but LaTeX does not `switch on' the
+``\cs{protect} mechanism'' for them.
+
+If you need to use the underscore character in these places, the
+package option \option[strings] is provided to redefine commands that
+take such a string argument so that protection is applied (with
+\cs{protect} made to be \cs{string}). The list of commands this
+provision affects is given in \cs{UnderscoreCommands}, with \cs{do}
+before each one; plus several others covering \cs{input},
+\cs{includegraphics}, \cs{cite}, \cs{ref}, and their variants. Not
+included are many commands regarding font names, anything with counter
+names, environment names, page styles, and versions of \cs{ref} and
+\cs{cite} defined by external packages (e.g., \cs{vref} and
+\cs{citeyear}).
+
+You can add to the list of supported commands by defining \cs{UnderscoreCommands}
+before loading this package; e.g.
+\begin{quote}
+\begin{verbatim}
+\usepackage{chicago}
+\newcommand{\UnderscoreCommands}{% (\cite already done)
+ \do\citeNP \do\citeA \do\citeANP \do\citeN \do\shortcite
+ \do\shortciteNP \do\shortciteA \do\shortciteANP \do\shortciteN
+ \do\citeyear \do\citeyearNP
+}
+\usepackage[strings]{underscore}
+\end{verbatim}
+\end{quote}
+
+Not all commands can be supported this way! Only commands that take a
+string argument \emph{first} can be protected. One optional argument before
+the string argument is also permitted, as exemplified by \cs{cite}: both
+\cmdinvoke{cite}{tags} and \cmdinvoke{cite}[text]{tags} are allowed.
+A command like \cs{@addtoreset} which takes two counter names as
+arguments could not be protected by listing it in \cs{UnderscoreCommands}.
+
+\textit{When you use the \option[strings] option, you must load this
+ package \textbf{last}} (or nearly last).
+There are two reasons for this requirement:
+\begin{enumerate}
+\item The redefinitions done for protection must come after other
+ packages define their customized versions of those commands.
+\item The \option[strings] option requires the ``\texttt{_}'' character to be
+ activated immediately in order for the cite and ref tags to be read
+ properly from the \texttt{.aux} file as plain strings, and this
+ catcode setting might disrupt other packages.
+\end{enumerate}
+
+The \Package{babel} package implements a protection mechanism for many
+commands, and will be a complete fix for most documents without the
+\option[strings] option. Many add-on packages are compatible with
+\Package{babel}, so they will get the strings protection also.
+However, there are several commands that are not covered by
+\Package{babel}, but can easily be supported by \option[strings] and
+\cs{UnderscoreCommands} mechanism. Beware the potential conflict
+using both \option[strings] and \Package{babel} (though none have been
+reported, yet); load babel last.
+
+\subsection*{Implementation notes}
+
+The first setting of ``\texttt{_}'' to be an active character is
+performed in a local group so as to not interfere with other packages.
+The catcode setting is repeated with ``\cs{AtBeginDocument}'' so the
+definition is in effect for the text. However, the catcode setting is
+repeated immediately when the \option[strings] option is detected.
+
+The definition of the active ``\texttt{_}'' is essentially:
+\begin{quote}
+ \cs{ifmmode} \cs{sb} \cs{else} \cs{BreakableUnderscore} \cs{fi}
+\end{quote}
+where \cs{sb} retains the normal subscript meaning of \texttt{_} and where
+\cs{BreakableUnderscore} is essentially \cs{_}. The rest of the definition
+handles the \cs{protect}ion without causing \cs{relax} to be inserted before
+the character.
+
+\cs{BreakableUnderscore} uses \cs{nobreak}\cs{hskip}\cs{z@skip} to separate the
+underscore from surrounding words, thus allowing \TeX{} to hyphenate them,
+but preventing free breaks around the underscore. Next, it checks the
+current font family, and uses the underscore character from tt fonts or
+otherwise \cs{textunderscore} (which is a character or rule depending on
+the font encoding). After the underscore, it inserts a discretionary
+hyphenation point as \cs{usc@dischyph}, which is usually just \cs{-}
+except that it still works in the tabbing environment; if the
+\option[nohyphen] option is in effect, the empty discretionary
+\cmdinvoke{discretionary}{}{}{} is used instead. After
+that, another piece of non-breaking interword glue is inserted.
+
+Ordinarily, the comparison \cs{ifx}\cs{f@family}\cs{ttdefault} will fail
+because \cs{ttdefault} is `long' whereas \cs{f@family} is
+not\footnote{the package author says ``boooo hisss'' about this\dots},
+but \cs{ttdefault} is redefined to be non-long \cs{AtBeginDocument}.
+
+The \cs{_} command is then defined to use \cs{BreakableUnderscore}.
+
+If the \option[strings] option has not been given, that is all!
+
+Under the \option[strings] option, the list of special commands is processed to:
+\begin{itemize}
+\item retain the original command as \cs{US_}\meta{command} (e.g., \cs{US_ref})
+\item redefine the command as \cs{US@prot}\cs{US_command} for ordinary
+ commands (\cs{US@prot}\cs{US_ref}) or as
+ \cs{US@protopt}\cs{US_command} when an optional argument is possible
+ (e.g., \cs{US@protopt}\cs{US_bibitem}).
+\item self-protecting commands (e.g., \cs{cite}) retain their
+ self-protection.
+\end{itemize}
+Diagnosing the state of the pre-existing command is done by painful
+contortions involving \cs{meaning}.
+
+\cs{US@prot} and \cs{US@protopt} read the argument, process it with
+\cs{protect} enabled, then invoke the saved \cs{US_command}.
+
+\end{document}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% End: