Debian Codegraph @

texmf-dist/doc/latex/underscore/underscore.tex

raw
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: