path: root/macros/latex/contrib/foreign/foreign.dtx

% \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'.