1% underscore.sty 21-Sep-2005 Donald Arseneau asnd@triumf.ca 2% Make the "_" character print as "\textunderscore" in text. 3% Copyright 1998,2001,2005,2006 Donald Arseneau; 4% License: LPPL version 1.2 or later. 5% Instructions follow after the definitions. 6 7\ProvidesPackage{underscore}[2006/09/13] 8 9\begingroup 10 \catcode`\_=\active 11 \gdef _{% \relax % No relax gives a small vulnerability in alignments 12 \ifx\if@safe@actives\iftrue % must be outermost test! 13 \string_% 14 \else 15 \ifx\protect\@typeset@protect 16 \ifmmode \sb \else \BreakableUnderscore \fi 17 \else 18 \ifx\protect\@unexpandable@protect \noexpand_% 19 \else \protect_% 20 \fi\fi 21 \fi} 22 \global\let\ActiveUnderscore=_ 23 \gdef\normalUnderscoreDef{\let_\ActiveUnderscore} 24\endgroup 25 26% At begin: set catcode; fix \long \ttdefault so I can use it in comparisons; 27% reapply definition of active _ in output routine (\@firstofone to strip 28% away braces, so avoiding deeper nesting). 29\AtBeginDocument{% 30 {\immediate\write\@auxout{\catcode\number\string`\_ \string\active}}% 31 \catcode\string`\_\string=\active 32 \edef\ttdefault{\ttdefault}% 33 \output=\expandafter\expandafter\expandafter 34 {\expandafter\expandafter\expandafter\normalUnderscoreDef 35 \expandafter\@firstofone\the\output}% 36} 37 38\newcommand{\BreakableUnderscore}{\leavevmode\nobreak\hskip\z@skip 39 \ifx\f@family\ttdefault \string_\else \textunderscore\fi 40 \usc@dischyph\nobreak\hskip\z@skip} 41 42\DeclareRobustCommand{\_}{% 43 \ifmmode \nfss@text{\textunderscore}\else \BreakableUnderscore \fi} 44 45 46\let\usc@dischyph\@dischyph 47\DeclareOption{nohyphen}{\def\usc@dischyph{\discretionary{}{}{}}} 48\DeclareOption{strings}{\catcode`\_=\active} 49 50\ProcessOptions 51\ifnum\catcode`\_=\active\else \endinput \fi 52 53%%%%%%%% Redefine commands that use character strings %%%%%%%% 54 55\@ifundefined{UnderscoreCommands}{\let\UnderscoreCommands\@empty}{} 56\expandafter\def\expandafter\UnderscoreCommands\expandafter{% 57 \UnderscoreCommands 58 \do\include \do\includeonly 59 \do\@input \do\@iinput \do\InputIfFileExists 60 \do\ref \do\pageref \do\newlabel 61 \do\bibitem \do\@bibitem \do\cite \do\nocite \do\bibcite 62 \do\Ginclude@graphics \do\@setckpt 63} 64 65% Macro to redefine a macro to pre-process its string argument 66% with \protect -> \string. 67\def\do#1{% Avoid double processing if user includes command twice! 68 \@ifundefined{US\string_\expandafter\@gobble\string#1}{% 69 \edef\@tempb{\meaning#1}% Check if macro is just a protection shell... 70 \def\@tempc{\protect}% 71 \edef\@tempc{\meaning\@tempc\string#1\space\space}% 72 \ifx\@tempb\@tempc % just a shell: hook into the protected inner command 73 \expandafter\do 74 \csname \expandafter\@gobble\string#1 \expandafter\endcsname 75 \else % Check if macro takes an optional argument 76 \def\@tempc{\@ifnextchar[}% 77 \edef\@tempa{\def\noexpand\@tempa####1\meaning\@tempc}% 78 \@tempa##2##3\@tempa{##2\relax}% 79 \edef\@tempb{\meaning#1\meaning\@tempc}% 80 \edef\@tempc{\noexpand\@tempd \csname 81 US\string_\expandafter\@gobble\string#1\endcsname}% 82 \if \expandafter\@tempa\@tempb \relax 12\@tempa % then no optional arg 83 \@tempc #1\US@prot 84 \else % There is optional arg 85 \@tempc #1\US@protopt 86 \fi 87 \fi 88 }{}} 89 90\def\@tempd#1#2#3{\let#1#2\def#2{#3#1}} 91 92\def\US@prot#1#2{\let\@@protect\protect \let\protect\string 93 \edef\US@temp##1{##1{#2}}\restore@protect\US@temp#1} 94\def\US@protopt#1{\@ifnextchar[{\US@protarg#1}{\US@prot#1}} 95\def\US@protarg #1[#2]{\US@prot{{#1[#2]}}} 96 97\UnderscoreCommands 98\let\do\relax \let\@tempd\relax % un-do 99 100%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 101 102\endinput 103 104underscore.sty 13-Sep-2006 Donald Arseneau 105 106Features: 107~~~~~~~~~ 108The "\_" command (which normally prints an underscore character or 109facsimile) is altered so that the hyphenation of constituent words 110is not affected, and hyphenation is permitted after the underscore. 111For example, "compound\_fracture" hyphenates as com- pound\_- frac- ture. 112If you prefer the underscore to break without a hyphen (but still with 113the same rules for explicit hyphen-breaks) then use the [nohyphen] 114package option. 115 116A simple "_" acts just like "\_" in text mode, but makes a subscript 117in math mode: activation_energy $E_a$ 118 119Both forms use an underscore character if the font encoding contains 120one (e.g., "\usepackage[T1]{fontenc}" or typewriter fonts in any encoding), 121but they use a rule if there is no proper character. 122 123Deficiencies: 124~~~~~~~~~~~~~ 125The skips and penalties ruin any kerning with the underscore character 126(when a character is used). However, there doesn't seem to be much, if 127any, such kerning in the ec fonts, and there is never any kerning with 128a rule. 129 130You must avoid "_" in file names and in cite or ref tags, or you must use 131the babel package, with its active-character controls, or you must give 132the [strings] option, which attempts to redefine several commands (and 133may not work perfectly). Even without the [strings] option or babel, you 134can use occasional underscores like: "\include{file\string_name}". 135 136Option: [strings] 137~~~~~~~~~~~~~~~~~ 138The default operation is quite simple and needs no customization; but 139you must avoid using "_" in any place where LaTeX uses an argument as 140a string of characters for some control function or as a name. These 141include the tags for "\cite" and "\ref", file names for "\input", 142"\include", and "\includegraphics", environment names, counter names, 143and placement parameters (like "[t]"). The problem with these contexts 144is that they are `moving arguments' but LaTeX does not `switch on' the 145"\protect" mechanism for them. 146 147If you need to use the underscore character in these places, the package 148option [strings] is provided to redefine commands that take such a string 149argument so that protection is applied (with "\protect" being "\string"). 150The list of commands is given in "\UnderscoreCommands", with "\do" before 151each; plus several others covering "\input", "\includegraphics, "\cite", 152"\ref", and their variants. Not included are many commands regarding font 153names, everything with counter names, environment names, page styles, and 154versions of "\ref" and "\cite" defined by external packages (e.g., "\vref" 155and "\citeyear"). 156 157You can add to the list of supported commands by defining "\UnderscoreCommands" 158before loading this package; e.g. 159 160 \usepackage{chicago} 161 \newcommand{\UnderscoreCommands}{% (\cite already done) 162 \do\citeNP \do\citeA \do\citeANP \do\citeN \do\shortcite 163 \do\shortciteNP \do\shortciteA \do\shortciteANP \do\shortciteN 164 \do\citeyear \do\citeyearNP 165 } 166 \usepackage[strings]{underscore} 167 168Not all commands can be supported this way! Only commands that take a 169string argument *first* can be protected. One optional argument before 170the string argument is also permitted, as exemplified by "\cite": both 171"\cite{tags}" and "\cite[text]{tags}" are allowed. A command like 172"\@addtoreset" which takes two counter names as arguments could not 173be protected by listing it in "\UnderscoreCommands". 174 175*When you use the [strings] option, you must load this package 176last* (or nearly last). 177 178There are two reasons: 1) The redefinitions done for protection must come 179after other packages define their customized versions of those commands. 1802) The [strings] option requires the "_" character to be activated immediately 181in order for the cite and ref tags to be read properly from the .aux file 182as plain strings, and this catcode setting might disrupt other packages. 183 184The babel package implements a protection mechanism for many commands, 185and will be a complete fix for most documents without the [strings] option. 186Many add-on packages are compatible with babel, so they will get the 187strings protection also. However, there are several commands that are 188not covered by babel, but can easily be supported by the [strings] and 189"\UnderscoreCommands" mechanism. Beware that using both [strings] and 190babel might lead to conflicts, but none are seen yet (load babel last). 191 192Implementation Notes: 193~~~~~~~~~~~~~~~~~~~~~ 194The first setting of "_" to be an active character is performed in a local 195group so as to not interfere with other packages. The catcode setting 196is repeated with "\AtBeginDocument" so the definition is in effect for the 197text. However, the catcode setting is repeated immediately when the 198[strings] option is detected. 199 200The definition of the active "_" is essentially: 201 202 \ifmmode \sb \else \BreakableUnderscore \fi 203 204where "\sb" retains the normal subscript meaning of "_" and where 205"\BreakableUnderscore" is essentially "\_". The rest of the definition 206handles the "\protect"ion without causing "\relax" to be inserted before 207the character. 208 209"\BreakableUnderscore" uses "\nobreak\hskip\z@skip" to separate the 210underscore from surrounding words, thus allowing TeX to hyphenate them, 211but preventing free breaks around the underscore. Next, it checks the 212current font family, and uses the underscore character from tt fonts or 213otherwise "\textunderscore" (which is a character or rule depending on 214the font encoding). After the underscore, it inserts a discretionary 215hyphenation point as "\usc@dischyph", which is usually just "\-" 216except that it still works in the tabbing environment, although it 217will give "\discretionary{}{}{}" under the [nohyphen] option. After 218that, another piece of non-breaking interword glue is inserted. 219Ordinarily, the comparison "\ifx\f@family\ttdefault" will always fail 220because "\ttdefault" is `long' whereas "\f@family" is not (boooo hisss), 221but "\ttdefault" is redefined to be non-long by "\AtBeginDocument". 222 223The "\_" command is then defined to use "\BreakableUnderscore". 224 225If the [strings] option is not given, then that is all! 226 227Under the [strings] option, the list of special commands is processed to: 228 229 - retain the original command as "\US_"*command* (e.g., "\US_ref") 230 - redefine the command as "\US@prot\US_command" for ordinary commands 231 ("\US@prot\US_ref") or as "\US@protopt\US_command" when an optional 232 argument is possible (e.g., "\US@protopt\US_bibitem"). 233 - self-protecting commands ("\cite") retain their self-protection. 234 235Diagnosing the state of the pre-existing command is done by painful 236contortions involving "\meaning". 237 238"\US@prot" and "\US@protopt" read the argument, process it with 239"\protect" enabled, then invoke the saved "\US_command". 240 241Modifications: 242~~~~~~~~~~~~~~ 24313-Sep-2006 Reassert my definition in the output routine (listings). 24421-Sep-2005 \includegraphics safe. 24512-Oct-2001 Babel (safe@actives) compatibility and [nohyphen] option. 246 247Test file integrity: ASCII 32-57, 58-126: !"#$%&'()*+,-./0123456789 248:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~ 249