summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/foreign/foreign.dtx
blob: d67339f0d3aba0bb1f67d5f8b89b7ca17c7c3014 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
% \iffalse meta-comment
%
% Copyright (C) 2012 by
%    Philip G. Ratcliffe <philip.ratcliffe@uninsubria.it>
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3c of this license or (at your option) any later
% version. The latest version of this license is in
%
%    http://www.latex-project.org/lppl.txt
%
% and version 1.3c or later is part of all distributions of
% LaTeX version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained.'
%
% The current maintainer of this work is Philip G. Ratcliffe.
%
% \fi
%
% \iffalse
%
%<package>\NeedsTeXFormat{LaTeX2e}[1995/12/01]
%<package>\ProvidesPackage{foreign}
%<package>   [2012/09/25 v2.7 type-setting package for foreign words (PGR)]
%
%<*driver>
\documentclass[british]{ltxdoc}
\usepackage[all]{foreign}
\providecommand\DescribeOther[1]{%
  \leavevmode
  \marginpar{\raggedleft\PrintDescribeEnv{#1}}%
  \index{#1|usage}\ignorespaces
}
\providecommand\via{via\xspace}
\renewcommand\thefootnote{\fnsymbol{footnote}}
\CodelineIndex
\EnableCrossrefs
\RecordChanges
\DoNotIndex{\def,\newcommand,\renewcommand}
\DoNotIndex{\if,\else,\fi,\ifx,\fi}
\DoNotIndex{\csname,\endcsname,\expandafter}
\DoNotIndex{\InputIfFileExists,\typeout}
\DoNotIndex{\`,\@empty,\ae}
%
\begin{document}
  \DocInput{foreign.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{205}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v1.0}{2004/11/21}{first non-public release}
% \changes{v2.5}{2012/06/18}{first public release}
% \changes{v2.6}{2012/06/20}{minor corrections to documentation}
% \changes{v2.7}{2012/09/25}{added capitalised abbreviations}
%
% \GetFileInfo{foreign.sty}
%
% \DoNotIndex{\CodelineIndex,\EnableCrossrefs,\RecordChanges}
%
% \title{
%   The \textsf{foreign}\relax
%   \thanks{
%     This file has version number \fileversion, and revision date \filedate.}
%   \space
%   package for \LaTeX2e
% }
% \author{
%   Philip G. Ratcliffe\thanks{E-mail: \textsf{philip.ratcliffe@uninsubria.it}}
% \\
%   Dipartimento di Scienze e Alta Tecnologia
% \\
%   Universit\`{a} degli Studi dell'Insubria---Como
% }
%
% \date{}
%
% \maketitle
%
% \begin{abstract}
% This package affords the user automatic typeface differentiation (\eg by
% italicising) of foreign (\eg Latin) words, phrases and abbreviations. It is
% supplied with a number of predefined words, phrases and abbreviations that
% should normally be italicised in an English text. Macros are automatically
% applied to add periods and/or commas, where necessary. Note that, since the
% basic definitions are universal in form, the package is easily adaptable to
% languages \emph{other} than English.
% \end{abstract}
%
% \section{Introduction}
%
% It is standard practice to distinguish foreign words and expressions \via the
% use of italics. The commands defined in this package are intended to aid in
% rendering this automatic and switchable; the default font change is
% \emph{emphasis} \via |\emph|.
%
% With regard to punctuation (periods) in abbreviations and the use of
% different fonts or typefaces, the choice (more-or-less unavoidably) has been
% made to \emph{exclude} such marks from any font changes; \ie they always
% appear in the current default text font. The problem is due to the presence
% of periods that may \emph{accidentally} coincide with natural sentence-ending
% full-stops. Since \LaTeX\ cannot determine the actual syntactic r\^{o}le of
% such periods and any method of signalling this externally would be inevitably
% cumbersome, the package author has decided on the simplest course of action.
%
% \section{Usage}
%
% The call format for the package is
% \begin{center}
%    |\usepackage[|\meta{options}|]{foreign}|,
% \end{center}
% \DescribeMacro{\defasforeign}
% \DescribeMacro{\defnotforeign}
% \DescribeMacro{\redefasforeign}
% \DescribeMacro{\redefnotforeign}
% while the syntax of the most general definition is
% \begin{center}
%   |\defasforeign[|\meta{foreignphrase}|]{|\meta{foreign phrase}|}|.
% \end{center}
% The above line defines |\foreignphrase| to expand as \emph{foreign phrase}.
% The optional argument is used to provide a legal command string when the word
% or phrase itself is unsuitable due to the presence of non-alphabetic
% characters, such as spaces (as in the example), accents, macros, numbers
% \etc. Thus, to define a single foreign word a call of the following type is
% sufficient:
% \begin{center}
%   |\defasforeign{caveat}|,
% \end{center}
% after which |\caveat| will expand to \caveat.
%
% A similar command |\defnotforeign| allows variation of preset default
% combinations; analogous macros |\redefasforeign| and |\redefnotforeign| are
% also defined. Note that any necessary capitalised versions must be defined
% additionally. Note also that trailing spaces are handled automatically \via
% the |xspace| package and its |\xspace| command.
%
% \DescribeMacro{\foreign}
% \DescribeMacro{\notforeign}
% \DescribeMacro{\foreignfullfont}
% \DescribeMacro{\foreignabbrfont}
% The two single-argument macros |\foreign| and |\notforeign| cause their
% arguments to be typeset in the desired manner. The font used for foreign
% words and phrases depends on the definition of |\foreignfullfont|, the
% default is |\emph|, but this may be redefined by the user \via
% |\renewcommand\foreignfullfont{|\dots|}|. Abbreviations are defined using
% |\foreignabbrfont|, default |\em|.
%
% \subsection{Options}

% \DescribeOther{abbreviations}
% \DescribeOther{xfrench}
% \DescribeOther{xgerman}
% \DescribeOther{xlatin}
% \DescribeOther{phrases}
% \DescribeOther{all}
% At present there are seven user options, four of which allow a few preset
% default definitions to be activated:
% \\[1ex]
% \begin{tabular}{@{\qquad}ll}
% |abbreviations| & foreign abbreviations, \\
% |xfrench|       & French words and phrases, \\
% |xgerman|       & German words and phrases, \\
% |xlatin|        & Latin words and phrases, \\
% |phrases|       & non-Latin foreign words and phrases, \\
% |all|           & \emph{all} of the above.
% \end{tabular}
% \\
% \DescribeOther{UKenglish}
% \DescribeOther{british}
% The remaining, |UKenglish| (|british| is a synonym), allows choosing no comma
% following the abbreviations ``\ie'' and ``\eg''; this is the generally
% recommended usage in British English. The default, recommended American,
% usage is to use a comma (both before and after).
%
% Note that if either the |UKenglish| or |british| option is present in the
% |\documentclass| statement (\eg for the |babel| package), then the
% |UKenglish| (|british|) option will be activated in the |foreign| package.
%
% \subsection{User configuration file}
%
% It may be convenient to create a |foreign.cfg| file for all user definitions,
% especially in the case of localisations. The package will automatically look
% for such a file on the \LaTeX\ search path.
%
% \subsection{Caveats}
%
% No particular care is necessary in using the commands defined by this package
% (they are ``robust''). However, it should be noted that the |\xspace| command
% does not generate space when appearing before ``|{|'' (even if there is an
% intervening space) and therefore in such a case a following ``\verb*+\ +'' or
% |\space| is required.
%
% \subsection{External package requirements}
%
% The |xpunctuate| and |xspace| packages are required for correct punctuation
% and trailing spaces (though see the above caveat)
%
% \subsection{Package conflicts}
%
% There are no known conflicts with any standard \LaTeX2e\ packages
%
% \StopEventually{\PrintChanges\PrintIndex}
%
% \section{Implementation}
%
% \subsection{External packages}
%
% Load the |xpunctuate|\footnote{The |xpunctuate| package is also by the author
% of the present package.} and |xspace| packages, for correct punctuation and
% trailing spaces.
%    \begin{macrocode}
\RequirePackage{xpunctuate,xspace}
%    \end{macrocode}
% The |xspace| package is loaded explicitly, despite being loaded by
% |xpunctuate|, as it is also used explicitly here.
%
% \subsection{User options}
%
% \subsection{User commands}
%
% \subsubsection{Foreign-word macros}
%
% \begin{macro}{\foreign}
% \begin{macro}{\notforeign}
% The macro |\foreign| prints the argument (word or phrase, but should be
% avoided for abbreviations) in the typeface predefined for foreign words (\eg
% italicised) while the macro |\notforeign| prints the argument (word or
% phrase) in the default text typeface (this allows choice of options according
% to the recommended usage):
%    \begin{macrocode}
\DeclareRobustCommand\foreign[1]{{\foreignfullfont{#1}}\xspace}
\DeclareRobustCommand\notforeign[1]{#1\xspace}
%    \end{macrocode}
% We use |\DeclareRobustCommand| to avoid problems (due to the action of
% |\xspace| \etc) when used inside so-called ``moving arguments''.
% \end{macro}
% \end{macro}
% \begin{macro}{\foreignfullfont}
% \begin{macro}{\foreignabbrfont}
% The user-redefinable macros |\foreignfullfont| and |\foreignabbrfont| invoke
% the font adopted for indicating foreign words and phrases, the default is
% |\emph| for unabbreviated words but |\em| for abbreviations, to avoid the
% extra space before the period:
%    \begin{macrocode}
\newcommand\foreignfullfont{\emph}
\newcommand\foreignabbrfont{\em}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\defasforeign}
% \begin{macro}{\defnotforeign}
% The macro |\defasforeign| defines a new command to represent a foreign (\eg
% italicised) word or phrase. Similarly, |\defnotforeign| defines a macro to
% represent a non-foreign (and therefore non-italicised) word or phrase.
%    \begin{macrocode}
\newcommand\defasforeign[2][]{%
  \define@foreign{#1}{#2}{\newcommand}{\foreign}
}
\newcommand\defnotforeign[2][]{%
  \define@foreign{#1}{#2}{\newcommand}{\notforeign}
}
%    \end{macrocode}
% Note that |\defasforeign| and |\defnotforeign| may \emph{not} be used
% successively with the \emph{same} arguments to reverse their effects; for
% such a behaviour use the following naturally defined commands.
% \end{macro}
% \end{macro}
%
% \begin{macro}{\redefasforeign}
% \begin{macro}{\redefnotforeign}
% The macros |\redefasforeign| and |\redefnotforeign| \emph{re}define their
% arguments (which must therefore have been previously defined, with either
% standard \LaTeX\ commands or those provided here) to represent foreign
% (italicised) and non-foreign (non-italicised) words or phrases.
%    \begin{macrocode}
\newcommand\redefasforeign[2][]{%
  \define@foreign{#1}{#2}{\renewcommand}{\foreign}
}
\newcommand\redefnotforeign[2][]{%
  \define@foreign{#1}{#2}{\renewcommand}{\notforeign}
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\define@foreign}
% Here is the engine to the previous four macros.
%    \begin{macrocode}
\newcommand\define@foreign[4]{%
  \def\foreign@csname{#1}%
  \ifx\foreign@csname\@empty
    \def\foreign@csname{#2}%
  \fi
  \expandafter#3\csname\foreign@csname\endcsname{#4{#2}}%
}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Predefined phrases}
%
% The following macros provide a short default set of (commonly italicised)
% foreign (including Latin) words, abbreviations and phrases. Their activation
% is triggered \via the package-call options |phrases|, |xfrench|, |xgerman|,
% |xlatin|, |abbreviations| or |all| (see above). Here are the options
% described above:
%
% \subsubsection{Foreign words, phrases and abbreviations}
%
% A few predefinitions are provided for words and expressions that are commonly
% italicised (at least according to standard British English usage).
%
% The following are common Latin words and phrases (which should normally be
% italicised):
%    \begin{macrocode}
\DeclareOption{xlatin}{%
  \defasforeign{addendum}
  \defasforeign{Addendum}
  \defasforeign[adhoc]{ad hoc}
  \defasforeign[Adhoc]{Ad hoc}
  \defasforeign[aposteriori]{a posteriori}
  \defasforeign[Aposteriori]{A posteriori}
  \defasforeign[apriori]{a priori}
  \defasforeign[Apriori]{A priori}
  \defasforeign{caveat}
  \defasforeign{Caveat}
  \defasforeign{circa}
  \defasforeign{Circa}
  \defasforeign{curriculum}
  \defasforeign{Curriculum}
  \defasforeign{erratum}
  \defasforeign{Erratum}
  \defasforeign{ibidem}
  \defasforeign{Ibidem}
  \defasforeign{idem}
  \defasforeign{Idem}
  \defasforeign{sic}
  \defasforeign{Sic}
  \defasforeign[viceversa]{vice versa}
  \defasforeign[Viceversa]{Vice versa}
  \defasforeign[vitae]{vit{\ae}}
  \defasforeign[Vitae]{Vit{\ae}}
}
%    \end{macrocode}
%
% Macros for (commonly used and italicised) French words and phrases:
%    \begin{macrocode}
\DeclareOption{xfrench}{%
  \defasforeign[ala]{\`{a} la}
  \defasforeign[Ala]{\`{A} la}
  \defasforeign[visavis]{vis \`{a} vis}
  \defasforeign[Visavis]{Vis \`{a} vis}
}
%    \end{macrocode}
%
% Macros for (commonly used and italicised) German words and phrases:
%    \begin{macrocode}
\DeclareOption{xgerman}{%
  \defasforeign{ansatz}
  \defasforeign{Ansatz}
  \defasforeign{gedanken}
  \defasforeign{Gedanken}
}
%    \end{macrocode}
%
% The following are commonly italicised abbreviations (as explained earlier, we
% choose to keep the periods in the surrounding font for uniformity):
%    \begin{macrocode}
\DeclareOption{abbreviations}{%
  \DeclareRobustCommand\cf{\UKUS@comma{{\foreignabbrfont{cf}}}}
  \DeclareRobustCommand\eg{%
    \UKUS@comma{{\foreignabbrfont{e}}.{\foreignabbrfont{g}}}}
  \DeclareRobustCommand\etal{\xperiodafter{{\foreignabbrfont{et al}}}}
  \DeclareRobustCommand\etc{\xperiodafter{{\foreignabbrfont{etc}}}}
  \DeclareRobustCommand\etseq{\xperiodafter{{\foreignabbrfont{et seq}}}}
  \DeclareRobustCommand\ibid{\xperiodafter{{\foreignabbrfont{ibid}}}}
  \DeclareRobustCommand\ie{%
    \UKUS@comma{{\foreignabbrfont{i}}.{\foreignabbrfont{e}}}}
  \DeclareRobustCommand\loccit{%
    {\foreignabbrfont{loc}}.\ \xperiodafter{{\foreignabbrfont{cit}}}}
  \DeclareRobustCommand\opcit{%
    {\foreignabbrfont{op}}.\ \xperiodafter{{\foreignabbrfont{cit}}}}
  \DeclareRobustCommand\viz{\xperiodafter{{\foreignabbrfont{viz}}}}
  \DeclareRobustCommand\Cf{\UKUS@comma{{\foreignabbrfont{Cf}}}}
  \DeclareRobustCommand\Eg{%
    \UKUS@comma{{\foreignabbrfont{E}}.{\foreignabbrfont{g}}}}
  \DeclareRobustCommand\Etal{\xperiodafter{{\foreignabbrfont{Et al}}}}
  \DeclareRobustCommand\Etc{\xperiodafter{{\foreignabbrfont{Etc}}}}
  \DeclareRobustCommand\Etseq{\xperiodafter{{\foreignabbrfont{Et seq}}}}
  \DeclareRobustCommand\Ibid{\xperiodafter{{\foreignabbrfont{Ibid}}}}
  \DeclareRobustCommand\Ie{%
    \UKUS@comma{{\foreignabbrfont{I}}.{\foreignabbrfont{e}}}}
  \DeclareRobustCommand\Loccit{%
    {\foreignabbrfont{Loc}}.\ \xperiodafter{{\foreignabbrfont{cit}}}}
  \DeclareRobustCommand\Opcit{%
    {\foreignabbrfont{Op}}.\ \xperiodafter{{\foreignabbrfont{cit}}}}
  \DeclareRobustCommand\Viz{\xperiodafter{{\foreignabbrfont{Viz}}}}
}
%    \end{macrocode}
%
% The possibility to choose between the standard U.S. (default) and
% U.K. usages (comma and no comma respectively following ``\eg'' and ``\ie'')
% is set up here.
%    \begin{macrocode}
\newcommand\UKUS@comma{\xperiodafter}
\DeclareOption{UKenglish}{\renewcommand\UKUS@comma{\xperiodafter}}
\DeclareOption{USenglish}{\renewcommand\UKUS@comma{\xperiodcommaafter}}
\ExecuteOptions{USenglish}
%    \end{macrocode}
% Add a pseudonym for U.K. English:
%    \begin{macrocode}
\DeclareOption{british}{\ExecuteOptions{UKenglish}}
%    \end{macrocode}
%
% \subsubsection{All non-Latin phrase definitions}
%
% All of the non-Latin preset phrase definitions (but not abbreviations) may be
% selected in one go with the option |phrases|:
%    \begin{macrocode}
\DeclareOption{phrases}{\ExecuteOptions{xfrench,xgerman}}
%    \end{macrocode}
%
% \subsubsection{All definitions}
%
% All of the preset options may be selected in one go with the option |all|:
%    \begin{macrocode}
\DeclareOption{all}{\ExecuteOptions{xlatin,phrases,abbreviations}}
%    \end{macrocode}
%
% \subsubsection{Final option processing}
%
% We may now process the chosen options:
%    \begin{macrocode}
\ProcessOptions
%    \end{macrocode}
%
% \subsection{Configuration file input}
%
% If a file named |foreign.cfg| is found on the \LaTeX\ search path, then it
% will be loaded (thus allowing a local default configuration). It would
% normally contain user definitions, redefinitions and, for example, any
% desired redefinitions of the font specification commands |\foreignfullfont|
% and |\foreignabbrfont|.
%    \begin{macrocode}
\InputIfFileExists{foreign.cfg}{%
  \typeout{%
    ============================================^^J%
    Loading local configuration file foreign.cfg^^J%
    ============================================%
  }
}{}%
%    \end{macrocode}
%
% \Finale
%
\endinput
%%
%% End of file `foreign.dtx'.