source: trunk/anuga_core/documentation/user_manual/underscore.sty @ 7951

Last change on this file since 7951 was 2363, checked in by ole, 18 years ago

Tried to move documentation again

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