1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
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:
|
