| 1 |
\documentclass[a4paper]{article} |
| 2 |
\usepackage[a4paper]{geometry} |
| 3 |
\usepackage{miscdoc} |
| 4 |
\usepackage[scaled=0.85]{luximono} |
| 5 |
\usepackage{underscore} |
| 6 |
\begin{document} |
| 7 |
\title{The \Package{underscore} package} |
| 8 |
\author{Donald Arseneau\thanks{Documentation file assembled by Robin |
| 9 |
Fairbairns}} |
| 10 |
\date{13 September 2006, version 1.0} |
| 11 |
\maketitle |
| 12 |
|
| 13 |
\section*{Features} |
| 14 |
|
| 15 |
The package alters the command \cs{_} (which normally prints |
| 16 |
an underscore character or facsimile) so that the hyphenation of |
| 17 |
constituent words is not affected, and hyphenation is permitted after |
| 18 |
the underscore. For example, |
| 19 |
\begin{quote} |
| 20 |
\texttt{compound\cs{_}fracture} |
| 21 |
\end{quote} |
| 22 |
hyphenates as |
| 23 |
\begin{quote} |
| 24 |
\texttt{com- pound\cs{_}- frac- ture} |
| 25 |
\end{quote} |
| 26 |
If you prefer the underscore to break without a hyphen (but still with |
| 27 |
the same rules as for explicit hyphen-breaks) then use the |
| 28 |
\option[nohyphen] package option. |
| 29 |
|
| 30 |
A simple ``\texttt{_}'' acts just like ``\cs{_}'' in text |
| 31 |
mode, but makes a subscript in maths mode, so |
| 32 |
\begin{quote} |
| 33 |
\ttfamily activation_energy \$E_a\$ |
| 34 |
\end{quote} |
| 35 |
is printed as |
| 36 |
\begin{quote} |
| 37 |
activation_energy $E_a$ |
| 38 |
\end{quote} |
| 39 |
|
| 40 |
Both forms use an underscore character if the font encoding contains |
| 41 |
one (e.g., with \cmdinvoke{usepackage}[T1]{fontenc} or typewriter |
| 42 |
fonts in any encoding), but they use a rule if there is no proper |
| 43 |
character (just as unmodified \LaTeX{} does). |
| 44 |
|
| 45 |
\section*{Deficiencies} |
| 46 |
|
| 47 |
The skips and penalties ruin any kerning with the underscore character |
| 48 |
(when a character is used). However, there doesn't seem to be much, if |
| 49 |
any, such kerning in the EC fonts, and there is never any kerning with |
| 50 |
a rule. |
| 51 |
|
| 52 |
You must avoid ``\texttt{_}'' in file names and in cite or ref tags, or you must |
| 53 |
use the \Package{babel} package, with its active-character controls, |
| 54 |
or you must give the \option[strings] option, which attempts to |
| 55 |
redefine several commands (and may not work perfectly). Even without |
| 56 |
the \option[strings] option or \Package{babel}, you can use occasional |
| 57 |
underscores like: ``\cmdinvoke{include}{file\string\string_name}''. |
| 58 |
|
| 59 |
\subsection*{Option \protect\option[strings]} |
| 60 |
|
| 61 |
The default operation is quite simple and needs no customization; but |
| 62 |
you must avoid using ``\texttt{_}'' in any place where LaTeX uses an argument |
| 63 |
as a string of characters for some control function or as a name. |
| 64 |
These include the tags for \cs{cite} and \cs{ref}, file names for \cs{input}, |
| 65 |
\cs{include}, and \cs{includegraphics}, environment names, counter names, |
| 66 |
and placement parameters (like \option[t]). The problem with these contexts |
| 67 |
is that they are `moving arguments' but LaTeX does not `switch on' the |
| 68 |
``\cs{protect} mechanism'' for them. |
| 69 |
|
| 70 |
If you need to use the underscore character in these places, the |
| 71 |
package option \option[strings] is provided to redefine commands that |
| 72 |
take such a string argument so that protection is applied (with |
| 73 |
\cs{protect} made to be \cs{string}). The list of commands this |
| 74 |
provision affects is given in \cs{UnderscoreCommands}, with \cs{do} |
| 75 |
before each one; plus several others covering \cs{input}, |
| 76 |
\cs{includegraphics}, \cs{cite}, \cs{ref}, and their variants. Not |
| 77 |
included are many commands regarding font names, anything with counter |
| 78 |
names, environment names, page styles, and versions of \cs{ref} and |
| 79 |
\cs{cite} defined by external packages (e.g., \cs{vref} and |
| 80 |
\cs{citeyear}). |
| 81 |
|
| 82 |
You can add to the list of supported commands by defining \cs{UnderscoreCommands} |
| 83 |
before loading this package; e.g. |
| 84 |
\begin{quote} |
| 85 |
\begin{verbatim} |
| 86 |
\usepackage{chicago} |
| 87 |
\newcommand{\UnderscoreCommands}{% (\cite already done) |
| 88 |
\do\citeNP \do\citeA \do\citeANP \do\citeN \do\shortcite |
| 89 |
\do\shortciteNP \do\shortciteA \do\shortciteANP \do\shortciteN |
| 90 |
\do\citeyear \do\citeyearNP |
| 91 |
} |
| 92 |
\usepackage[strings]{underscore} |
| 93 |
\end{verbatim} |
| 94 |
\end{quote} |
| 95 |
|
| 96 |
Not all commands can be supported this way! Only commands that take a |
| 97 |
string argument \emph{first} can be protected. One optional argument before |
| 98 |
the string argument is also permitted, as exemplified by \cs{cite}: both |
| 99 |
\cmdinvoke{cite}{tags} and \cmdinvoke{cite}[text]{tags} are allowed. |
| 100 |
A command like \cs{@addtoreset} which takes two counter names as |
| 101 |
arguments could not be protected by listing it in \cs{UnderscoreCommands}. |
| 102 |
|
| 103 |
\textit{When you use the \option[strings] option, you must load this |
| 104 |
package \textbf{last}} (or nearly last). |
| 105 |
There are two reasons for this requirement: |
| 106 |
\begin{enumerate} |
| 107 |
\item The redefinitions done for protection must come after other |
| 108 |
packages define their customized versions of those commands. |
| 109 |
\item The \option[strings] option requires the ``\texttt{_}'' character to be |
| 110 |
activated immediately in order for the cite and ref tags to be read |
| 111 |
properly from the \texttt{.aux} file as plain strings, and this |
| 112 |
catcode setting might disrupt other packages. |
| 113 |
\end{enumerate} |
| 114 |
|
| 115 |
The \Package{babel} package implements a protection mechanism for many |
| 116 |
commands, and will be a complete fix for most documents without the |
| 117 |
\option[strings] option. Many add-on packages are compatible with |
| 118 |
\Package{babel}, so they will get the strings protection also. |
| 119 |
However, there are several commands that are not covered by |
| 120 |
\Package{babel}, but can easily be supported by \option[strings] and |
| 121 |
\cs{UnderscoreCommands} mechanism. Beware the potential conflict |
| 122 |
using both \option[strings] and \Package{babel} (though none have been |
| 123 |
reported, yet); load babel last. |
| 124 |
|
| 125 |
\subsection*{Implementation notes} |
| 126 |
|
| 127 |
The first setting of ``\texttt{_}'' to be an active character is |
| 128 |
performed in a local group so as to not interfere with other packages. |
| 129 |
The catcode setting is repeated with ``\cs{AtBeginDocument}'' so the |
| 130 |
definition is in effect for the text. However, the catcode setting is |
| 131 |
repeated immediately when the \option[strings] option is detected. |
| 132 |
|
| 133 |
The definition of the active ``\texttt{_}'' is essentially: |
| 134 |
\begin{quote} |
| 135 |
\cs{ifmmode} \cs{sb} \cs{else} \cs{BreakableUnderscore} \cs{fi} |
| 136 |
\end{quote} |
| 137 |
where \cs{sb} retains the normal subscript meaning of \texttt{_} and where |
| 138 |
\cs{BreakableUnderscore} is essentially \cs{_}. The rest of the definition |
| 139 |
handles the \cs{protect}ion without causing \cs{relax} to be inserted before |
| 140 |
the character. |
| 141 |
|
| 142 |
\cs{BreakableUnderscore} uses \cs{nobreak}\cs{hskip}\cs{z@skip} to separate the |
| 143 |
underscore from surrounding words, thus allowing \TeX{} to hyphenate them, |
| 144 |
but preventing free breaks around the underscore. Next, it checks the |
| 145 |
current font family, and uses the underscore character from tt fonts or |
| 146 |
otherwise \cs{textunderscore} (which is a character or rule depending on |
| 147 |
the font encoding). After the underscore, it inserts a discretionary |
| 148 |
hyphenation point as \cs{usc@dischyph}, which is usually just \cs{-} |
| 149 |
except that it still works in the tabbing environment; if the |
| 150 |
\option[nohyphen] option is in effect, the empty discretionary |
| 151 |
\cmdinvoke{discretionary}{}{}{} is used instead. After |
| 152 |
that, another piece of non-breaking interword glue is inserted. |
| 153 |
|
| 154 |
Ordinarily, the comparison \cs{ifx}\cs{f@family}\cs{ttdefault} will fail |
| 155 |
because \cs{ttdefault} is `long' whereas \cs{f@family} is |
| 156 |
not\footnote{the package author says ``boooo hisss'' about this\dots}, |
| 157 |
but \cs{ttdefault} is redefined to be non-long \cs{AtBeginDocument}. |
| 158 |
|
| 159 |
The \cs{_} command is then defined to use \cs{BreakableUnderscore}. |
| 160 |
|
| 161 |
If the \option[strings] option has not been given, that is all! |
| 162 |
|
| 163 |
Under the \option[strings] option, the list of special commands is processed to: |
| 164 |
\begin{itemize} |
| 165 |
\item retain the original command as \cs{US_}\meta{command} (e.g., \cs{US_ref}) |
| 166 |
\item redefine the command as \cs{US@prot}\cs{US_command} for ordinary |
| 167 |
commands (\cs{US@prot}\cs{US_ref}) or as |
| 168 |
\cs{US@protopt}\cs{US_command} when an optional argument is possible |
| 169 |
(e.g., \cs{US@protopt}\cs{US_bibitem}). |
| 170 |
\item self-protecting commands (e.g., \cs{cite}) retain their |
| 171 |
self-protection. |
| 172 |
\end{itemize} |
| 173 |
Diagnosing the state of the pre-existing command is done by painful |
| 174 |
contortions involving \cs{meaning}. |
| 175 |
|
| 176 |
\cs{US@prot} and \cs{US@protopt} read the argument, process it with |
| 177 |
\cs{protect} enabled, then invoke the saved \cs{US_command}. |
| 178 |
|
| 179 |
\end{document} |
| 180 |
|
| 181 |
%%% Local Variables: |
| 182 |
%%% mode: latex |
| 183 |
%%% TeX-master: t |
| 184 |
%%% End: |