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