doc-src/underscore.sty
changeset 26862 a79d7d5f1d06
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc-src/underscore.sty	Fri May 09 12:44:31 2008 +0200
     1.3 @@ -0,0 +1,248 @@
     1.4 +% underscore.sty     21-Sep-2005   Donald Arseneau   asnd@triumf.ca
     1.5 +% Make the "_" character print as "\textunderscore" in text.
     1.6 +% Copyright 1998,2001,2005,2006 Donald Arseneau;  
     1.7 +% License: LPPL version 1.2 or later.
     1.8 +% Instructions follow after the definitions.
     1.9 +
    1.10 +\ProvidesPackage{underscore}[2006/09/13]
    1.11 +
    1.12 +\begingroup
    1.13 + \catcode`\_=\active
    1.14 + \gdef _{% \relax % No relax gives a small vulnerability in alignments
    1.15 +   \ifx\if@safe@actives\iftrue % must be outermost test!
    1.16 +      \string_%
    1.17 +   \else
    1.18 +      \ifx\protect\@typeset@protect
    1.19 +         \ifmmode \sb \else \BreakableUnderscore \fi
    1.20 +      \else
    1.21 +         \ifx\protect\@unexpandable@protect \noexpand_%
    1.22 +         \else \protect_%
    1.23 +      \fi\fi
    1.24 +    \fi}
    1.25 +  \global\let\ActiveUnderscore=_
    1.26 +  \gdef\normalUnderscoreDef{\let_\ActiveUnderscore}
    1.27 +\endgroup
    1.28 +
    1.29 +% At begin: set catcode; fix \long \ttdefault so I can use it in comparisons; 
    1.30 +% reapply definition of active _ in output routine (\@firstofone to strip
    1.31 +% away braces, so avoiding deeper nesting).
    1.32 +\AtBeginDocument{%
    1.33 +  {\immediate\write\@auxout{\catcode\number\string`\_ \string\active}}%
    1.34 +  \catcode\string`\_\string=\active
    1.35 +  \edef\ttdefault{\ttdefault}%
    1.36 +  \output=\expandafter\expandafter\expandafter
    1.37 +     {\expandafter\expandafter\expandafter\normalUnderscoreDef
    1.38 +      \expandafter\@firstofone\the\output}%
    1.39 +}
    1.40 +
    1.41 +\newcommand{\BreakableUnderscore}{\leavevmode\nobreak\hskip\z@skip
    1.42 + \ifx\f@family\ttdefault \string_\else \textunderscore\fi
    1.43 + \usc@dischyph\nobreak\hskip\z@skip}
    1.44 +
    1.45 +\DeclareRobustCommand{\_}{%
    1.46 +  \ifmmode \nfss@text{\textunderscore}\else \BreakableUnderscore \fi}
    1.47 +
    1.48 +
    1.49 +\let\usc@dischyph\@dischyph
    1.50 +\DeclareOption{nohyphen}{\def\usc@dischyph{\discretionary{}{}{}}}
    1.51 +\DeclareOption{strings}{\catcode`\_=\active}
    1.52 +
    1.53 +\ProcessOptions
    1.54 +\ifnum\catcode`\_=\active\else \endinput \fi
    1.55 +
    1.56 +%%%%%%%%   Redefine commands that use character strings   %%%%%%%%
    1.57 +
    1.58 +\@ifundefined{UnderscoreCommands}{\let\UnderscoreCommands\@empty}{}
    1.59 +\expandafter\def\expandafter\UnderscoreCommands\expandafter{%
    1.60 +  \UnderscoreCommands
    1.61 +  \do\include \do\includeonly
    1.62 +  \do\@input \do\@iinput \do\InputIfFileExists
    1.63 +  \do\ref \do\pageref \do\newlabel
    1.64 +  \do\bibitem \do\@bibitem \do\cite \do\nocite \do\bibcite
    1.65 +  \do\Ginclude@graphics \do\@setckpt
    1.66 +}
    1.67 +
    1.68 +% Macro to redefine a macro to pre-process its string argument
    1.69 +% with \protect -> \string.
    1.70 +\def\do#1{% Avoid double processing if user includes command twice!
    1.71 + \@ifundefined{US\string_\expandafter\@gobble\string#1}{%
    1.72 +   \edef\@tempb{\meaning#1}% Check if macro is just a protection shell...
    1.73 +   \def\@tempc{\protect}%
    1.74 +   \edef\@tempc{\meaning\@tempc\string#1\space\space}%
    1.75 +   \ifx\@tempb\@tempc % just a shell: hook into the protected inner command
    1.76 +     \expandafter\do
    1.77 +       \csname \expandafter\@gobble\string#1 \expandafter\endcsname
    1.78 +   \else % Check if macro takes an optional argument
    1.79 +     \def\@tempc{\@ifnextchar[}%
    1.80 +     \edef\@tempa{\def\noexpand\@tempa####1\meaning\@tempc}%
    1.81 +     \@tempa##2##3\@tempa{##2\relax}%
    1.82 +     \edef\@tempb{\meaning#1\meaning\@tempc}%
    1.83 +     \edef\@tempc{\noexpand\@tempd \csname
    1.84 +        US\string_\expandafter\@gobble\string#1\endcsname}%
    1.85 +     \if \expandafter\@tempa\@tempb \relax 12\@tempa % then no optional arg
    1.86 +       \@tempc #1\US@prot
    1.87 +     \else  % There is optional arg
    1.88 +       \@tempc #1\US@protopt
    1.89 +     \fi
    1.90 +   \fi
    1.91 + }{}}
    1.92 +
    1.93 +\def\@tempd#1#2#3{\let#1#2\def#2{#3#1}}
    1.94 +
    1.95 +\def\US@prot#1#2{\let\@@protect\protect \let\protect\string
    1.96 +  \edef\US@temp##1{##1{#2}}\restore@protect\US@temp#1}
    1.97 +\def\US@protopt#1{\@ifnextchar[{\US@protarg#1}{\US@prot#1}}
    1.98 +\def\US@protarg #1[#2]{\US@prot{{#1[#2]}}}
    1.99 +
   1.100 +\UnderscoreCommands
   1.101 +\let\do\relax \let\@tempd\relax  % un-do
   1.102 +
   1.103 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   1.104 +
   1.105 +\endinput
   1.106 +
   1.107 +underscore.sty    13-Sep-2006  Donald Arseneau
   1.108 +
   1.109 +Features:
   1.110 +~~~~~~~~~
   1.111 +The "\_" command (which normally prints an underscore character or
   1.112 +facsimile) is altered so that the hyphenation of constituent words
   1.113 +is not affected, and hyphenation is permitted after the underscore.
   1.114 +For example, "compound\_fracture" hyphenates as com- pound\_- frac- ture.
   1.115 +If you prefer the underscore to break without a hyphen (but still with 
   1.116 +the same rules for explicit hyphen-breaks) then use the [nohyphen]
   1.117 +package option.
   1.118 +
   1.119 +A simple "_" acts just like "\_" in text mode, but makes a subscript
   1.120 +in math mode: activation_energy $E_a$
   1.121 +
   1.122 +Both forms use an underscore character if the font encoding contains
   1.123 +one (e.g., "\usepackage[T1]{fontenc}" or typewriter fonts in any encoding),
   1.124 +but they use a rule if there is no proper character.
   1.125 +
   1.126 +Deficiencies:
   1.127 +~~~~~~~~~~~~~
   1.128 +The skips and penalties ruin any kerning with the underscore character
   1.129 +(when a character is used).  However, there doesn't seem to be much, if
   1.130 +any, such kerning in the ec fonts, and there is never any kerning with
   1.131 +a rule.
   1.132 +
   1.133 +You must avoid "_" in file names and in cite or ref tags, or you must use 
   1.134 +the babel package, with its active-character controls, or you must give 
   1.135 +the [strings] option, which attempts to redefine several commands (and 
   1.136 +may not work perfectly).  Even without the [strings] option or babel, you 
   1.137 +can use occasional underscores like: "\include{file\string_name}".
   1.138 +
   1.139 +Option: [strings]
   1.140 +~~~~~~~~~~~~~~~~~
   1.141 +The default operation is quite simple and needs no customization; but
   1.142 +you must avoid using "_" in any place where LaTeX uses an argument as
   1.143 +a string of characters for some control function or as a name.  These
   1.144 +include the tags for "\cite" and "\ref", file names for "\input", 
   1.145 +"\include", and "\includegraphics", environment names, counter names,
   1.146 +and placement parameters (like "[t]").  The problem with these contexts
   1.147 +is that they are `moving arguments' but LaTeX does not `switch on' the
   1.148 +"\protect" mechanism for them.
   1.149 +
   1.150 +If you need to use the underscore character in these places, the package
   1.151 +option [strings] is provided to redefine commands that take such a string
   1.152 +argument so that protection is applied (with "\protect" being "\string").
   1.153 +The list of commands is given in "\UnderscoreCommands", with "\do" before
   1.154 +each; plus several others covering "\input", "\includegraphics, "\cite", 
   1.155 +"\ref", and their variants.  Not included are many commands regarding font 
   1.156 +names, everything with counter names, environment names, page styles, and 
   1.157 +versions of "\ref" and "\cite" defined by external packages (e.g., "\vref" 
   1.158 +and "\citeyear").
   1.159 +
   1.160 +You can add to the list of supported commands by defining "\UnderscoreCommands"
   1.161 +before loading this package; e.g.
   1.162 +
   1.163 +   \usepackage{chicago}
   1.164 +   \newcommand{\UnderscoreCommands}{%   (\cite already done)
   1.165 +     \do\citeNP \do\citeA \do\citeANP \do\citeN \do\shortcite
   1.166 +     \do\shortciteNP \do\shortciteA \do\shortciteANP \do\shortciteN
   1.167 +     \do\citeyear \do\citeyearNP
   1.168 +   }
   1.169 +   \usepackage[strings]{underscore}
   1.170 +
   1.171 +Not all commands can be supported this way!  Only commands that take a
   1.172 +string argument *first* can be protected.  One optional argument before
   1.173 +the string argument is also permitted, as exemplified by "\cite": both
   1.174 +"\cite{tags}" and "\cite[text]{tags}" are allowed.  A command like
   1.175 +"\@addtoreset" which takes two counter names as arguments could not
   1.176 +be protected by listing it in "\UnderscoreCommands".
   1.177 +
   1.178 +*When you use the [strings] option, you must load this package
   1.179 +last* (or nearly last).
   1.180 +
   1.181 +There are two reasons: 1) The redefinitions done for protection must come
   1.182 +after other packages define their customized versions of those commands.
   1.183 +2) The [strings] option requires the "_" character to be activated immediately
   1.184 +in order for the cite and ref tags to be read properly from the .aux file
   1.185 +as plain strings, and this catcode setting might disrupt other packages.
   1.186 +
   1.187 +The babel package implements a protection mechanism for many commands,
   1.188 +and will be a complete fix for most documents without the [strings] option.
   1.189 +Many add-on packages are compatible with babel, so they will get the
   1.190 +strings protection also.  However, there are several commands that are 
   1.191 +not covered by babel, but can easily be supported by the [strings] and 
   1.192 +"\UnderscoreCommands" mechanism.  Beware that using both [strings] and
   1.193 +babel might lead to conflicts, but none are seen yet (load babel last).
   1.194 +
   1.195 +Implementation Notes:
   1.196 +~~~~~~~~~~~~~~~~~~~~~
   1.197 +The first setting of "_" to be an active character is performed in a local
   1.198 +group so as to not interfere with other packages.  The catcode setting
   1.199 +is repeated with "\AtBeginDocument" so the definition is in effect for the
   1.200 +text.  However, the catcode setting is repeated immediately when the
   1.201 +[strings] option is detected.
   1.202 +
   1.203 +The definition of the active "_" is essentially:
   1.204 +
   1.205 +       \ifmmode \sb \else \BreakableUnderscore \fi
   1.206 +
   1.207 +where "\sb" retains the normal subscript meaning of "_" and where
   1.208 +"\BreakableUnderscore" is essentially "\_".  The rest of the definition
   1.209 +handles the "\protect"ion without causing "\relax" to be inserted before
   1.210 +the character.
   1.211 +
   1.212 +"\BreakableUnderscore" uses "\nobreak\hskip\z@skip" to separate the
   1.213 +underscore from surrounding words, thus allowing TeX to hyphenate them,
   1.214 +but preventing free breaks around the underscore. Next, it checks the
   1.215 +current font family, and uses the underscore character from tt fonts or
   1.216 +otherwise "\textunderscore" (which is a character or rule depending on
   1.217 +the font encoding).  After the underscore, it inserts a discretionary
   1.218 +hyphenation point as "\usc@dischyph", which is usually just "\-"
   1.219 +except that it still works in the tabbing environment, although it
   1.220 +will give "\discretionary{}{}{}" under the [nohyphen] option.  After
   1.221 +that, another piece of non-breaking interword glue is inserted. 
   1.222 +Ordinarily, the comparison "\ifx\f@family\ttdefault" will always fail 
   1.223 +because "\ttdefault" is `long' whereas "\f@family" is not (boooo hisss),
   1.224 +but "\ttdefault" is redefined to be non-long by "\AtBeginDocument".
   1.225 +
   1.226 +The "\_" command is then defined to use "\BreakableUnderscore".
   1.227 +
   1.228 +If the [strings] option is not given, then that is all!
   1.229 +
   1.230 +Under the [strings] option, the list of special commands is processed to:
   1.231 +
   1.232 + - retain the original command as "\US_"*command* (e.g., "\US_ref")
   1.233 + - redefine the command as "\US@prot\US_command" for ordinary commands
   1.234 +   ("\US@prot\US_ref") or as "\US@protopt\US_command" when an optional
   1.235 +   argument is possible (e.g., "\US@protopt\US_bibitem").
   1.236 + - self-protecting commands ("\cite") retain their self-protection.
   1.237 +
   1.238 +Diagnosing the state of the pre-existing command is done by painful
   1.239 +contortions involving "\meaning".
   1.240 +
   1.241 +"\US@prot" and "\US@protopt" read the argument, process it with 
   1.242 +"\protect" enabled, then invoke the saved "\US_command".
   1.243 +
   1.244 +Modifications:
   1.245 +~~~~~~~~~~~~~~
   1.246 +13-Sep-2006  Reassert my definition in the output routine (listings).
   1.247 +21-Sep-2005  \includegraphics safe.
   1.248 +12-Oct-2001  Babel (safe@actives) compatibility and [nohyphen] option.
   1.249 +
   1.250 +Test file integrity:  ASCII 32-57, 58-126:  !"#$%&'()*+,-./0123456789
   1.251 +:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~