Debian Codegraph @

texmf-dist/source/latex/foreign/foreign.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2012 by
4 % Philip G. Ratcliffe <[email protected]>
5 %
6 % This work may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either
8 % version 1.3c of this license or (at your option) any later
9 % version. The latest version of this license is in
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of
14 % LaTeX version 2005/12/01 or later.
15 %
16 % This work has the LPPL maintenance status `maintained.'
17 %
18 % The current maintainer of this work is Philip G. Ratcliffe.
19 %
20 % \fi
21 %
22 % \iffalse
23 %
24 %<package>\NeedsTeXFormat{LaTeX2e}[1995/12/01]
25 %<package>\ProvidesPackage{foreign}
26 %<package> [2012/09/25 v2.7 type-setting package for foreign words (PGR)]
27 %
28 %<*driver>
29 \documentclass[british]{ltxdoc}
30 \usepackage[all]{foreign}
31 \providecommand\DescribeOther[1]{%
32 \leavevmode
33 \marginpar{\raggedleft\PrintDescribeEnv{#1}}%
34 \index{#1|usage}\ignorespaces
35 }
36 \providecommand\via{via\xspace}
37 \renewcommand\thefootnote{\fnsymbol{footnote}}
38 \CodelineIndex
39 \EnableCrossrefs
40 \RecordChanges
41 \DoNotIndex{\def,\newcommand,\renewcommand}
42 \DoNotIndex{\if,\else,\fi,\ifx,\fi}
43 \DoNotIndex{\csname,\endcsname,\expandafter}
44 \DoNotIndex{\InputIfFileExists,\typeout}
45 \DoNotIndex{\`,\@empty,\ae}
46 %
47 \begin{document}
48 \DocInput{foreign.dtx}
49 \end{document}
50 %</driver>
51 % \fi
52 %
53 % \CheckSum{205}
54 %
55 % \CharacterTable
56 % {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
57 % 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
58 % Digits \0\1\2\3\4\5\6\7\8\9
59 % Exclamation \! Double quote \" Hash (number) \#
60 % Dollar \$ Percent \% Ampersand \&
61 % Acute accent \' Left paren \( Right paren \)
62 % Asterisk \* Plus \+ Comma \,
63 % Minus \- Point \. Solidus \/
64 % Colon \: Semicolon \; Less than \<
65 % Equals \= Greater than \> Question mark \?
66 % Commercial at \@ Left bracket \[ Backslash \\
67 % Right bracket \] Circumflex \^ Underscore \_
68 % Grave accent \` Left brace \{ Vertical bar \|
69 % Right brace \} Tilde \~}
70 %
71 %
72 % \changes{v1.0}{2004/11/21}{first non-public release}
73 % \changes{v2.5}{2012/06/18}{first public release}
74 % \changes{v2.6}{2012/06/20}{minor corrections to documentation}
75 % \changes{v2.7}{2012/09/25}{added capitalised abbreviations}
76 %
77 % \GetFileInfo{foreign.sty}
78 %
79 % \DoNotIndex{\CodelineIndex,\EnableCrossrefs,\RecordChanges}
80 %
81 % \title{
82 % The \textsf{foreign}\relax
83 % \thanks{
84 % This file has version number \fileversion, and revision date \filedate.}
85 % \space
86 % package for \LaTeX2e
87 % }
88 % \author{
89 % Philip G. Ratcliffe\thanks{E-mail: \textsf{[email protected]}}
90 % \\
91 % Dipartimento di Scienze e Alta Tecnologia
92 % \\
93 % Universit\`{a} degli Studi dell'Insubria---Como
94 % }
95 %
96 % \date{}
97 %
98 % \maketitle
99 %
100 % \begin{abstract}
101 % This package affords the user automatic typeface differentiation (\eg by
102 % italicising) of foreign (\eg Latin) words, phrases and abbreviations. It is
103 % supplied with a number of predefined words, phrases and abbreviations that
104 % should normally be italicised in an English text. Macros are automatically
105 % applied to add periods and/or commas, where necessary. Note that, since the
106 % basic definitions are universal in form, the package is easily adaptable to
107 % languages \emph{other} than English.
108 % \end{abstract}
109 %
110 % \section{Introduction}
111 %
112 % It is standard practice to distinguish foreign words and expressions \via the
113 % use of italics. The commands defined in this package are intended to aid in
114 % rendering this automatic and switchable; the default font change is
115 % \emph{emphasis} \via |\emph|.
116 %
117 % With regard to punctuation (periods) in abbreviations and the use of
118 % different fonts or typefaces, the choice (more-or-less unavoidably) has been
119 % made to \emph{exclude} such marks from any font changes; \ie they always
120 % appear in the current default text font. The problem is due to the presence
121 % of periods that may \emph{accidentally} coincide with natural sentence-ending
122 % full-stops. Since \LaTeX\ cannot determine the actual syntactic r\^{o}le of
123 % such periods and any method of signalling this externally would be inevitably
124 % cumbersome, the package author has decided on the simplest course of action.
125 %
126 % \section{Usage}
127 %
128 % The call format for the package is
129 % \begin{center}
130 % |\usepackage[|\meta{options}|]{foreign}|,
131 % \end{center}
132 % \DescribeMacro{\defasforeign}
133 % \DescribeMacro{\defnotforeign}
134 % \DescribeMacro{\redefasforeign}
135 % \DescribeMacro{\redefnotforeign}
136 % while the syntax of the most general definition is
137 % \begin{center}
138 % |\defasforeign[|\meta{foreignphrase}|]{|\meta{foreign phrase}|}|.
139 % \end{center}
140 % The above line defines |\foreignphrase| to expand as \emph{foreign phrase}.
141 % The optional argument is used to provide a legal command string when the word
142 % or phrase itself is unsuitable due to the presence of non-alphabetic
143 % characters, such as spaces (as in the example), accents, macros, numbers
144 % \etc. Thus, to define a single foreign word a call of the following type is
145 % sufficient:
146 % \begin{center}
147 % |\defasforeign{caveat}|,
148 % \end{center}
149 % after which |\caveat| will expand to \caveat.
150 %
151 % A similar command |\defnotforeign| allows variation of preset default
152 % combinations; analogous macros |\redefasforeign| and |\redefnotforeign| are
153 % also defined. Note that any necessary capitalised versions must be defined
154 % additionally. Note also that trailing spaces are handled automatically \via
155 % the |xspace| package and its |\xspace| command.
156 %
157 % \DescribeMacro{\foreign}
158 % \DescribeMacro{\notforeign}
159 % \DescribeMacro{\foreignfullfont}
160 % \DescribeMacro{\foreignabbrfont}
161 % The two single-argument macros |\foreign| and |\notforeign| cause their
162 % arguments to be typeset in the desired manner. The font used for foreign
163 % words and phrases depends on the definition of |\foreignfullfont|, the
164 % default is |\emph|, but this may be redefined by the user \via
165 % |\renewcommand\foreignfullfont{|\dots|}|. Abbreviations are defined using
166 % |\foreignabbrfont|, default |\em|.
167 %
168 % \subsection{Options}
169
170 % \DescribeOther{abbreviations}
171 % \DescribeOther{xfrench}
172 % \DescribeOther{xgerman}
173 % \DescribeOther{xlatin}
174 % \DescribeOther{phrases}
175 % \DescribeOther{all}
176 % At present there are seven user options, four of which allow a few preset
177 % default definitions to be activated:
178 % \\[1ex]
179 % \begin{tabular}{@{\qquad}ll}
180 % |abbreviations| & foreign abbreviations, \\
181 % |xfrench| & French words and phrases, \\
182 % |xgerman| & German words and phrases, \\
183 % |xlatin| & Latin words and phrases, \\
184 % |phrases| & non-Latin foreign words and phrases, \\
185 % |all| & \emph{all} of the above.
186 % \end{tabular}
187 % \\
188 % \DescribeOther{UKenglish}
189 % \DescribeOther{british}
190 % The remaining, |UKenglish| (|british| is a synonym), allows choosing no comma
191 % following the abbreviations ``\ie'' and ``\eg''; this is the generally
192 % recommended usage in British English. The default, recommended American,
193 % usage is to use a comma (both before and after).
194 %
195 % Note that if either the |UKenglish| or |british| option is present in the
196 % |\documentclass| statement (\eg for the |babel| package), then the
197 % |UKenglish| (|british|) option will be activated in the |foreign| package.
198 %
199 % \subsection{User configuration file}
200 %
201 % It may be convenient to create a |foreign.cfg| file for all user definitions,
202 % especially in the case of localisations. The package will automatically look
203 % for such a file on the \LaTeX\ search path.
204 %
205 % \subsection{Caveats}
206 %
207 % No particular care is necessary in using the commands defined by this package
208 % (they are ``robust''). However, it should be noted that the |\xspace| command
209 % does not generate space when appearing before ``|{|'' (even if there is an
210 % intervening space) and therefore in such a case a following ``\verb*+\ +'' or
211 % |\space| is required.
212 %
213 % \subsection{External package requirements}
214 %
215 % The |xpunctuate| and |xspace| packages are required for correct punctuation
216 % and trailing spaces (though see the above caveat)
217 %
218 % \subsection{Package conflicts}
219 %
220 % There are no known conflicts with any standard \LaTeX2e\ packages
221 %
222 % \StopEventually{\PrintChanges\PrintIndex}
223 %
224 % \section{Implementation}
225 %
226 % \subsection{External packages}
227 %
228 % Load the |xpunctuate|\footnote{The |xpunctuate| package is also by the author
229 % of the present package.} and |xspace| packages, for correct punctuation and
230 % trailing spaces.
231 % \begin{macrocode}
232 \RequirePackage{xpunctuate,xspace}
233 % \end{macrocode}
234 % The |xspace| package is loaded explicitly, despite being loaded by
235 % |xpunctuate|, as it is also used explicitly here.
236 %
237 % \subsection{User options}
238 %
239 % \subsection{User commands}
240 %
241 % \subsubsection{Foreign-word macros}
242 %
243 % \begin{macro}{\foreign}
244 % \begin{macro}{\notforeign}
245 % The macro |\foreign| prints the argument (word or phrase, but should be
246 % avoided for abbreviations) in the typeface predefined for foreign words (\eg
247 % italicised) while the macro |\notforeign| prints the argument (word or
248 % phrase) in the default text typeface (this allows choice of options according
249 % to the recommended usage):
250 % \begin{macrocode}
251 \DeclareRobustCommand\foreign[1]{{\foreignfullfont{#1}}\xspace}
252 \DeclareRobustCommand\notforeign[1]{#1\xspace}
253 % \end{macrocode}
254 % We use |\DeclareRobustCommand| to avoid problems (due to the action of
255 % |\xspace| \etc) when used inside so-called ``moving arguments''.
256 % \end{macro}
257 % \end{macro}
258 % \begin{macro}{\foreignfullfont}
259 % \begin{macro}{\foreignabbrfont}
260 % The user-redefinable macros |\foreignfullfont| and |\foreignabbrfont| invoke
261 % the font adopted for indicating foreign words and phrases, the default is
262 % |\emph| for unabbreviated words but |\em| for abbreviations, to avoid the
263 % extra space before the period:
264 % \begin{macrocode}
265 \newcommand\foreignfullfont{\emph}
266 \newcommand\foreignabbrfont{\em}
267 % \end{macrocode}
268 % \end{macro}
269 % \end{macro}
270 %
271 % \begin{macro}{\defasforeign}
272 % \begin{macro}{\defnotforeign}
273 % The macro |\defasforeign| defines a new command to represent a foreign (\eg
274 % italicised) word or phrase. Similarly, |\defnotforeign| defines a macro to
275 % represent a non-foreign (and therefore non-italicised) word or phrase.
276 % \begin{macrocode}
277 \newcommand\defasforeign[2][]{%
278 \define@foreign{#1}{#2}{\newcommand}{\foreign}
279 }
280 \newcommand\defnotforeign[2][]{%
281 \define@foreign{#1}{#2}{\newcommand}{\notforeign}
282 }
283 % \end{macrocode}
284 % Note that |\defasforeign| and |\defnotforeign| may \emph{not} be used
285 % successively with the \emph{same} arguments to reverse their effects; for
286 % such a behaviour use the following naturally defined commands.
287 % \end{macro}
288 % \end{macro}
289 %
290 % \begin{macro}{\redefasforeign}
291 % \begin{macro}{\redefnotforeign}
292 % The macros |\redefasforeign| and |\redefnotforeign| \emph{re}define their
293 % arguments (which must therefore have been previously defined, with either
294 % standard \LaTeX\ commands or those provided here) to represent foreign
295 % (italicised) and non-foreign (non-italicised) words or phrases.
296 % \begin{macrocode}
297 \newcommand\redefasforeign[2][]{%
298 \define@foreign{#1}{#2}{\renewcommand}{\foreign}
299 }
300 \newcommand\redefnotforeign[2][]{%
301 \define@foreign{#1}{#2}{\renewcommand}{\notforeign}
302 }
303 % \end{macrocode}
304 % \end{macro}
305 % \end{macro}
306 %
307 % \begin{macro}{\define@foreign}
308 % Here is the engine to the previous four macros.
309 % \begin{macrocode}
310 \newcommand\define@foreign[4]{%
311 \def\foreign@csname{#1}%
312 \ifx\foreign@csname\@empty
313 \def\foreign@csname{#2}%
314 \fi
315 \expandafter#3\csname\foreign@csname\endcsname{#4{#2}}%
316 }
317 % \end{macrocode}
318 % \end{macro}
319 %
320 % \subsection{Predefined phrases}
321 %
322 % The following macros provide a short default set of (commonly italicised)
323 % foreign (including Latin) words, abbreviations and phrases. Their activation
324 % is triggered \via the package-call options |phrases|, |xfrench|, |xgerman|,
325 % |xlatin|, |abbreviations| or |all| (see above). Here are the options
326 % described above:
327 %
328 % \subsubsection{Foreign words, phrases and abbreviations}
329 %
330 % A few predefinitions are provided for words and expressions that are commonly
331 % italicised (at least according to standard British English usage).
332 %
333 % The following are common Latin words and phrases (which should normally be
334 % italicised):
335 % \begin{macrocode}
336 \DeclareOption{xlatin}{%
337 \defasforeign{addendum}
338 \defasforeign{Addendum}
339 \defasforeign[adhoc]{ad hoc}
340 \defasforeign[Adhoc]{Ad hoc}
341 \defasforeign[aposteriori]{a posteriori}
342 \defasforeign[Aposteriori]{A posteriori}
343 \defasforeign[apriori]{a priori}
344 \defasforeign[Apriori]{A priori}
345 \defasforeign{caveat}
346 \defasforeign{Caveat}
347 \defasforeign{circa}
348 \defasforeign{Circa}
349 \defasforeign{curriculum}
350 \defasforeign{Curriculum}
351 \defasforeign{erratum}
352 \defasforeign{Erratum}
353 \defasforeign{ibidem}
354 \defasforeign{Ibidem}
355 \defasforeign{idem}
356 \defasforeign{Idem}
357 \defasforeign{sic}
358 \defasforeign{Sic}
359 \defasforeign[viceversa]{vice versa}
360 \defasforeign[Viceversa]{Vice versa}
361 \defasforeign[vitae]{vit{\ae}}
362 \defasforeign[Vitae]{Vit{\ae}}
363 }
364 % \end{macrocode}
365 %
366 % Macros for (commonly used and italicised) French words and phrases:
367 % \begin{macrocode}
368 \DeclareOption{xfrench}{%
369 \defasforeign[ala]{\`{a} la}
370 \defasforeign[Ala]{\`{A} la}
371 \defasforeign[visavis]{vis \`{a} vis}
372 \defasforeign[Visavis]{Vis \`{a} vis}
373 }
374 % \end{macrocode}
375 %
376 % Macros for (commonly used and italicised) German words and phrases:
377 % \begin{macrocode}
378 \DeclareOption{xgerman}{%
379 \defasforeign{ansatz}
380 \defasforeign{Ansatz}
381 \defasforeign{gedanken}
382 \defasforeign{Gedanken}
383 }
384 % \end{macrocode}
385 %
386 % The following are commonly italicised abbreviations (as explained earlier, we
387 % choose to keep the periods in the surrounding font for uniformity):
388 % \begin{macrocode}
389 \DeclareOption{abbreviations}{%
390 \DeclareRobustCommand\cf{\UKUS@comma{{\foreignabbrfont{cf}}}}
391 \DeclareRobustCommand\eg{%
392 \UKUS@comma{{\foreignabbrfont{e}}.{\foreignabbrfont{g}}}}
393 \DeclareRobustCommand\etal{\xperiodafter{{\foreignabbrfont{et al}}}}
394 \DeclareRobustCommand\etc{\xperiodafter{{\foreignabbrfont{etc}}}}
395 \DeclareRobustCommand\etseq{\xperiodafter{{\foreignabbrfont{et seq}}}}
396 \DeclareRobustCommand\ibid{\xperiodafter{{\foreignabbrfont{ibid}}}}
397 \DeclareRobustCommand\ie{%
398 \UKUS@comma{{\foreignabbrfont{i}}.{\foreignabbrfont{e}}}}
399 \DeclareRobustCommand\loccit{%
400 {\foreignabbrfont{loc}}.\ \xperiodafter{{\foreignabbrfont{cit}}}}
401 \DeclareRobustCommand\opcit{%
402 {\foreignabbrfont{op}}.\ \xperiodafter{{\foreignabbrfont{cit}}}}
403 \DeclareRobustCommand\viz{\xperiodafter{{\foreignabbrfont{viz}}}}
404 \DeclareRobustCommand\Cf{\UKUS@comma{{\foreignabbrfont{Cf}}}}
405 \DeclareRobustCommand\Eg{%
406 \UKUS@comma{{\foreignabbrfont{E}}.{\foreignabbrfont{g}}}}
407 \DeclareRobustCommand\Etal{\xperiodafter{{\foreignabbrfont{Et al}}}}
408 \DeclareRobustCommand\Etc{\xperiodafter{{\foreignabbrfont{Etc}}}}
409 \DeclareRobustCommand\Etseq{\xperiodafter{{\foreignabbrfont{Et seq}}}}
410 \DeclareRobustCommand\Ibid{\xperiodafter{{\foreignabbrfont{Ibid}}}}
411 \DeclareRobustCommand\Ie{%
412 \UKUS@comma{{\foreignabbrfont{I}}.{\foreignabbrfont{e}}}}
413 \DeclareRobustCommand\Loccit{%
414 {\foreignabbrfont{Loc}}.\ \xperiodafter{{\foreignabbrfont{cit}}}}
415 \DeclareRobustCommand\Opcit{%
416 {\foreignabbrfont{Op}}.\ \xperiodafter{{\foreignabbrfont{cit}}}}
417 \DeclareRobustCommand\Viz{\xperiodafter{{\foreignabbrfont{Viz}}}}
418 }
419 % \end{macrocode}
420 %
421 % The possibility to choose between the standard U.S. (default) and
422 % U.K. usages (comma and no comma respectively following ``\eg'' and ``\ie'')
423 % is set up here.
424 % \begin{macrocode}
425 \newcommand\UKUS@comma{\xperiodafter}
426 \DeclareOption{UKenglish}{\renewcommand\UKUS@comma{\xperiodafter}}
427 \DeclareOption{USenglish}{\renewcommand\UKUS@comma{\xperiodcommaafter}}
428 \ExecuteOptions{USenglish}
429 % \end{macrocode}
430 % Add a pseudonym for U.K. English:
431 % \begin{macrocode}
432 \DeclareOption{british}{\ExecuteOptions{UKenglish}}
433 % \end{macrocode}
434 %
435 % \subsubsection{All non-Latin phrase definitions}
436 %
437 % All of the non-Latin preset phrase definitions (but not abbreviations) may be
438 % selected in one go with the option |phrases|:
439 % \begin{macrocode}
440 \DeclareOption{phrases}{\ExecuteOptions{xfrench,xgerman}}
441 % \end{macrocode}
442 %
443 % \subsubsection{All definitions}
444 %
445 % All of the preset options may be selected in one go with the option |all|:
446 % \begin{macrocode}
447 \DeclareOption{all}{\ExecuteOptions{xlatin,phrases,abbreviations}}
448 % \end{macrocode}
449 %
450 % \subsubsection{Final option processing}
451 %
452 % We may now process the chosen options:
453 % \begin{macrocode}
454 \ProcessOptions
455 % \end{macrocode}
456 %
457 % \subsection{Configuration file input}
458 %
459 % If a file named |foreign.cfg| is found on the \LaTeX\ search path, then it
460 % will be loaded (thus allowing a local default configuration). It would
461 % normally contain user definitions, redefinitions and, for example, any
462 % desired redefinitions of the font specification commands |\foreignfullfont|
463 % and |\foreignabbrfont|.
464 % \begin{macrocode}
465 \InputIfFileExists{foreign.cfg}{%
466 \typeout{%
467 ============================================^^J%
468 Loading local configuration file foreign.cfg^^J%
469 ============================================%
470 }
471 }{}%
472 % \end{macrocode}
473 %
474 % \Finale
475 %
476 \endinput
477 %%
478 %% End of file `foreign.dtx'.