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

% \iffalse
%<*docdriver>
\documentclass{ltxdoc}[1996/01/11]
\begin{filecontents}{eemeir.ins}
% The eemeir package, version 1.1
\input docstrip.tex
\preamble

 m This is the E-Em-Eir package
 o Copyright 2003-07 by Mogens Lemvig Hansen,
 g Please find my e-mail address in the left margin
 e
 n Run eemeir.dtx through LaTeX and read the documentation in eemeir.dvi
 s
 @ This work may be distributed and/or modified under the
 k conditions of the LaTeX Project Public License, either version 1.3
 a of this license or (at your option) any later version.
 y The latest version of this license is in
 j   http://www.latex-project.org/lppl.txt
 u and version 1.3 or later is part of all distributions of LaTeX
 . version 2003/12/01 or later.
 c
 o This work has the LPPL maintenance status 'maintained'.
 m
   The Current Maintainer of this work is Mogens Lemvig Hansen.

   This work consists of the files eemeir.dtx and eemeir.ins
   and the derived file eemeir.sty.

\endpreamble
% I think that \path:twoup.sty: should go into the directory
% \path:tex/latex/misc:; however, \textsc{DocStrip} will not heed my advise
% unless your configuration file, \path:docstrip.cfg:, allows it to.
\usedir{tex/latex/misc}
\generate{\file{eemeir.sty}{\from{eemeir.dtx}{package}}}
\endbatchfile
\end{filecontents}
\usepackage{url,randtext}
\usepackage[male]{eemeir}
\InputIfFileExists{../myemail}{}{%
   \def\myemail{See top of .sty file for e-mail address}}
\CodelineIndex%\EnableCrossrefs
\makeatletter
\newcommand{\nextlinelabel}[2][1]{\@bsphack
   \@tempcnta\c@CodelineNo
   \advance\@tempcnta#1\relax
   \def\@currentlabel{\the\@tempcnta}\label{#2}%
   \@esphack}
\makeatother
\DocInput{eemeir.dtx}
\end{document}
%</docdriver>
% \fi
% \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         \~}
%
% \CheckSum{163}
% \GetFileInfo{eemeir.sty} \def\docdate{\filedate}
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{eemeir}[2007/02/19 v1.1 E-Em-Eir package]
% \fi
% \title{The E--Em--Eir package^^A
% \thanks{This file describes version \fileversion, \filedate.}
% }
% \author{\copyright\ Mogens Lemvig Hansen\\\myemail}
% \date{\docdate}
%
% \MakeShortVerb{\"}
% \setcounter{secnumdepth}{-99}
%
% \newenvironment{example}
%    {\begin{quote}\raggedright\ttfamily}
%    {\end{quote}}
% \newenvironment{syntax}
%    {\begin{quote}}
%    {\end{quote}}
%
% \begin{document}
% \maketitle
% \begin{abstract}
% The \textsf{E--Em--Eir} package facilitates writing documents that
% must be produced in both a male and a female form by providing
% natural and easily remembered commands (control sequences) to
% type in place of gender specific words.
% \end{abstract}
%
%
% I had occasion to write a couple of documents that needed to be printed
% in both a male and a female version.  To accomplish that conveniently,
% I developed this \textsf{E--Em--Eir} package which
% provides four commands,
% \DescribeMacro{\E}
% \DescribeMacro{\Em}
% \DescribeMacro{\Eir}
% \DescribeMacro{\Eirs}
% "\E", "\Em", "\Eir", and "\Eirs",
% that expand to personal pronouns depending on gender as follows:
% \begin{center}
% \begin{tabular}{lcc}
%              & Male& Female\\[2pt]
% "\E"    & he  & she\\
% "\Em"   & him & her\\
% "\Eir"  & his & her\\
% "\Eirs" & his & hers
% \end{tabular}
% \end{center}
% Thus,
% just as `I' is the first person singular pronoun, regardless of gender, so
% "\E" stands the third person singular pronoun for both genders:
% "\E" is the singular of `they'.  Accordingly, "\Eir" and
% "\Eirs" (pronounced to
% rhyme with `their(s)') are the possessives, and "\Em" (rhyming with
% `them') stands for either `him' or `her'.\footnote{I first encountered
% the pronouns `E', `Em', and `Eir' in M.D.~Spivak's \emph{The Joy of \TeX}
% and I have adapted the description of those pronouns from there.}
%
% For example,
% \begin{example}
% The user neglects reading the documentation at
% "\Eir" peril
% \end{example}
% expands to ``The user neglects reading the documentation at his peril''
% or ``The user neglects reading the documentation at her peril''
% depending on gender.
% Note that "\Eir" (and the other pronoun commands) automatically
% add a space after the pronoun where appropriate.\footnote{Curtesy of
% David Carlisle's \textsf{xspace} package
% which is required by the \textsf{E--Em--Eir}
% package and included in most distributions of \TeX.}
%
% \DescribeMacro{\swapgender}
% You can change gender~(!) mid stream with the "\swapgender" command.
% Thus
% \begin{example}
% "\E*" loves "\swapgender\Em" for "\Eir" body
% \end{example}
% expands to either ``She loves him for his body'' or ``He loves her for her body.''
% Note that the starred form of the pronoun commands yields a capitalized pronoun.
% The "\swapgender" command is a \emph{declaration} like "\large":
% its effect lasts until the end of the enclosing block (or until the
% gender is explicitly changed again).
% \DescribeEnv{swapgender}
% Like the font size commands, you can also use an environment
% form:
% \begin{example}
% "\E*" always praises "\begin{swapgender}" "\Eir" cooking; and
% "\E" "\end{swapgender}" loves "\Em" for it.
% \end{example}
% expands to ``She always praises his cooking; and he loves her for it.''
%
% \DescribeMacro{\newwordpair}
% You can easily add more commands like "\E" and friends.  For
% example,
% \begin{example}
% "\newwordpair{\child}{son}{daughter}"
%
% You say your "\child's" name and
% "\E" is marked with God's sign so that God knows
% "\Em" as His own.  Thus, the Sign of the Cross is a promise that God's
% love can always find your "\child."
% \end{example}
% expands to ``You say your daughter's name and
% she is marked with God's sign so that God knows
% her as His own.  Thus, the Sign of the Cross is a promise that God's
% love can always find your daughter\@.''\ in the female case.
% You could also write "grand\child" for grandson or
% granddaughter, etc.
%
% Other extensions come to mind:
% \begin{example}
% "\newwordpair{\parent}{father}{mother}"\\
% "\newwordpair{\spouse}{husband}{wife}"\\
% "\newwordpair{\sibling}{brother}{sister}"\\
% "\newwordpair{\nogoodnameforthisone}{nephew}{niece}"\\
% "\newwordpair{\orforthis}{uncle}{aunt}"\\
% "\newwordpair{\Mx}{Mr}{Ms}"
% \end{example}
% Each command defined by "\newwordpair" adds a space after the
% word where appropriate, and each has a starred form that capitalizes
% the word.
% \DescribeMacro{\renewwordpair}
% There is also a "\renewwordpair" command if you should want to re-define
% a command.
%
% \DescribeMacro{\ifmale}
% The commands defined by "\newwordpair" are intended to supply a single
% gender-specific word.
% If a whole phrase needs to be different, you can use
% the "\ifmale"--"\else"--"\fi" construct:
% \begin{example}
% \dots "\E" is expected to wear\verb*: \ifmale: smoking,
% patent leather shoes, and top hat"\else"
% full-length evening gown\verb*:\fi\ :for the gala.
% \end{example}
% This construct is provided by plain \TeX, so avoiding spurious spaces
% is the user's responsibility.
% If you find yourself using this construct often, you should have a look
% at the \textsf{optional} package and\slash or the \textsf{version} package.
%
% You set the gender when you load the \textsf{E--Em--Eir} package with
% "\usepackage" in the preamble:
% \begin{syntax}
% "\usepackage"\oarg{option}"{"\textsf{eemeir}"}"
% \end{syntax}
% The \meta{option} can be one of
% "male", "female", or the default, "ask".
% \DescribeMacro{\male}
% \DescribeMacro{\female}
% \DescribeMacro{\askforgender}
% You can also set the gender (at any reasonable place in your document) with
% one of the commands "\male", "\female", or "\askforgender"---and
% don't forget "\swapgender".
%
% \DescribeMacro{\male[...]}
% \DescribeMacro{\female[...]}
% A document can of course refer to the gender of more than one
% person.  The \textsf{E--Em--Eir} package can therefore keep track of
% more than one person:  Define a new person by giving an optional
% argument to "\male", "\female", or "\askforgender".
% Then give the same optional argument to "\E" or any other command
% defined by "\newwordpair" to use the gender of that person.
% For example,
% \begin{example}
% "\female[pastor]"
%
% Let your "\child" face the pastor so "\E[pastor]"
% can\dots
% \end{example}
% expands to ``Let your son face the pastor so she can\dots''\ if the
% main gender is male and "\child" has been defined as above.
% Once you have set the gender of a new person with, say,
% "\female[pastor]", you can change the gender with
% "\swapgender[pastor]" (or "\begin{swapgender}[pastor]"\dots) and
% the "\ifmale" construct for this person becomes
% "\ifmalepastor"--"\else"--"\fi".
%
%
% \section{Summary}
% \DescribeMacro{\newwordpair}
% \DescribeMacro{\renewwordpair}
% Define new commands or re-define old ones with
% \begin{syntax}
% "\newwordpair"\marg{cmd}\marg{male}\marg{female}\\
% "\renewwordpair"\marg{cmd}\marg{male}\marg{female}
% \end{syntax}
% Then \meta{cmd} is used like
% \begin{syntax}
% \meta{cmd}\oarg{person}\\
% \meta{cmd}"*"\oarg{person}
% \end{syntax}
% The un-starred version expands to \meta{male} or \meta{female} depending on
% the current gender of \meta{person} or the main gender in the absence of the
% optional argument.  Similarly, the starred version expands to \meta{male} or
% \meta{female} with the first letter capitalized.\footnote{If you
% want more than just the first letter capitalized, enclose the
% desired letters in braces:
% If
% \texttt{\bslash newwordpair\{\bslash
% strange\}\{\{ab\}cd\}\{\{def\}gh\}},
% then \texttt{\bslash strange*} expands
% to ``ABcd'' or ``DEFgh''.}
%
% \DescribeMacro{\male}
% \DescribeMacro{\female}
% \DescribeMacro{\askforgender}
% You set the \meta{person} gender (or the main gender in the absence of the
% optional argument) with one of the commands
% \begin{syntax}
% "\male"\oarg{person}\\
% "\female"\oarg{person}\\
% "\askforgender"\oarg{person}
% \end{syntax}
% You can also set the main gender with one of the options "male",
% "female", or "ask" (the default) when you load the \textsf{E--Em--Eir}
% package.
% \DescribeMacro{\swapgender}\DescribeEnv{swapgender}
% Once a gender has been set, you can change it with
% \begin{syntax}
% "\swapgender"\oarg{person}
% \end{syntax}
% or
% \begin{syntax}
% "\begin{swapgender}"\oarg{person} \dots "\end{swapgender}"
% \end{syntax}
%
% \DescribeMacro{\ifmale[...]}
% If you have longer passages that are gender specific, you can
% enclose them in "\ifmale"\meta{person}--"\else"--"\fi" or
% "\ifmale"--"\else"--"\fi" in case of the main gender.  If you use
% this construct often, either you have misunderstood the purpose of
% the \textsf{E--Em--Eir} package or I should extend it with some suitable
% environment for conditional inclusion of blocks of text. Let me
% know\dots
%
% \section{Installation}
% As you must have figured, you
% generate the documentation for the \textsf{E--Em--Eir} package
% by running the file \url:eemeir.dtx: through
% \LaTeX---twice to resolve cross references.\footnote{If you want an index,
% you must run MakeIndex
% (\texttt{makeindex -s gind.ist eemeir}) between the two
% \LaTeX{} runs.}
%
% To extract the \url{.sty} file from \url{eemeir.dtx},
% run \url:eemeir.ins: through \LaTeX.
% You now have to decide what to do with several files.
% \begin{itemize}
% \item Move the file \url:eemeir.sty: to some
% directory where \LaTeX\ can find it; the natural choice would be
% \url:(local)texmf/tex/latex/misc:.
% \item Move the documentation, \url:eemeir.dvi:, to
% \url:(local)texmf/doc/latex/misc:.
% \item You may discard the source files, \url:eemeir.dtx: and
% \url:eemeir.ins:, or store them in
% \url:(local)texmf/source/latex/misc:.
% \end{itemize}
%
% \section{License}\label{sec:license}
% This program may be distributed and/or modified under the
% conditions of the \LaTeX\ Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   \url;http://www.latex-project.org/lppl.txt;
% and version 1.3 or later is part of all distributions of \LaTeX \
% version 2003/12/01 or later.
%
% This program consists of the files \url:eemeir.dtx: and
% \url:eemeir.ins:.
%
% \StopEventually{
%    \PrintIndex
% }
%
% \section{Implementation}
% \begin{macro}{\@eemeir}
% \begin{macro}{\@eemeirM}
% \begin{macro}{\@eemeirF}
% We need a few control sequences for temporary storage.  Define
% them first with "\newcommand" to verify that they are not in use.
%    \begin{macrocode}
%<*package>
\newcommand{\@eemeir}{\relax}
\newcommand{\@eemeirM}{\relax}
\newcommand{\@eemeirF}{\relax}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
% Then declare the options.
%    \begin{macrocode}
\DeclareOption{male}  {\def\@eemeir{\male[]}}
\DeclareOption{female}{\def\@eemeir{\female[]}}
\DeclareOption{ask}   {\def\@eemeir{\askforgender[]}}
\ExecuteOptions{ask}
%    \end{macrocode}
% No matter how many options are processed, in the end "\@eemeir"
% will (obviously) contain only one of "\male[]", "\female[]", or
% "\askforgender[]".  On code line~\ref{ln:@eemeir} we'll call on
% "\@eemeir" to set the main gender.
%    \begin{macrocode}
\ProcessOptions
\RequirePackage{xspace}
%    \end{macrocode}
% \begin{macro}{\male}
% We use  "\@bsphack" and "\@esphack" to ensure that in things like
% \verb*: \male[...] : only one of the spaces is typeset.
% Below, "\ifmale#1" is "\ifmale" if the optional argument is
% blank and "\ifmale"\meta{person} if the optional argument is
% \meta{person}.
% Thus, if "\ifmale#1" is undefined, we define a new person by
% creating a new "\ifmale..." (and otherwise we "\relax").
%    \begin{macrocode}
\newcommand{\male}[1][]{%
   \@bsphack
   \@ifundefined{ifmale#1}
      {\expandafter\newif\csname ifmale#1\endcsname}
      {\relax}%
%    \end{macrocode}
% Then set the switch to "true" by calling "\maletrue" or
% "\male"\meta{person}"true" depending on the optional argument.
%    \begin{macrocode}
   \csname male#1true\endcsname
   \@esphack}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\female}
% "\female" is similar; just set the switch with
% "\male"\meta{person}"false".
%    \begin{macrocode}
\newcommand{\female}[1][]{%
   \@bsphack
   \@ifundefined{ifmale#1}
      {\expandafter\newif\csname ifmale#1\endcsname}
      {\relax}%
   \csname male#1false\endcsname
   \@esphack}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\askforgender}
% "\askforgender" begins just as "\male" and "\female".
%    \begin{macrocode}
\newcommand{\askforgender}[1][]{%
   \@bsphack
   \@ifundefined{ifmale#1}
      {\expandafter\newif\csname ifmale#1\endcsname}
      {\relax}%
%    \end{macrocode}
% Then use the temporary variable "\@eemeir" to help type out a
% pretty message---and store the answer again in "\@eemeir".
%    \begin{macrocode}
   \def\@eemeir{#1}%
   \ifx\@eemeir\@empty\def\@eemeir{main}\fi
   \typein[\@eemeir]{Specify the \@eemeir\space gender:%
      \space\space male\space\space or\space\space female}%
%    \end{macrocode}
% In order to provide a helpful error message if the user types
% anything but ``male'' or ``female'', we must carefully compare the
% answer against the legal ones; otherwise a call to
% "\csname\@eemeir\endcsname[#1]" would have sufficed.
%    \begin{macrocode}
   \def\@eemeirM{male}%
   \def\@eemeirF{female}%
   \ifx\@eemeir\@eemeirM\male[#1]%
   \else\ifx\@eemeir\@eemeirF\female[#1]%
   \else\PackageError{eemeir}
      {I'll ignore that}
      {You should have typed either\space\space male\space\space
         or\space\space female}%
   \fi\fi
   \@esphack
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\swapgender}
% \begin{environment}{swapgender}
% "\newenvironment{swapgender}" defines the command "\swapgender" to
% be called at the beginning of the environment (and another command
% to call at the end).  We therefore only have to worry about the
% environment case.
% Changing a gender that hasn't been set is meaningless, so
% "swapgender" insists that "\ifmale#1" is defined.
%    \begin{macrocode}
\newenvironment{swapgender}[1][]{%
   \@bsphack
   \@ifundefined{ifmale#1}
      {\PackageError{eemeir}{unknown gender: #1}
         {You must set the #1 gender with \string\male\space
            (or...) first.}}
%    \end{macrocode}
% If it's defined, swap it.
%    \begin{macrocode}
      {\csname ifmale#1\endcsname\csname male#1false\endcsname
       \else\csname male#1true\endcsname\fi}%
   \@esphack}
%    \end{macrocode}
% The "\end{swapgender}" only has to close the group (which is done
% by \LaTeX\ automatically) and use the space hacks to ensure that
% only one space is typeset in cases like \verb*: \end{swapgender} :.
%    \begin{macrocode}
   {\@bsphack\@Esphack}
%    \end{macrocode}
% \end{environment}\end{macro}
% \begin{macro}{\newwordpair}
% \begin{macro}{\renewwordpair}
% "\newwordpair" and "\renewwordpair" differ only in which command
% they employ to make the definition.
%    \begin{macrocode}
\newcommand{\newwordpair}  {\@newwordpair\newcommand}
\newcommand{\renewwordpair}{\@newwordpair\renewcommand}
%    \end{macrocode}
% \begin{macro}{\@newwordpair}
% The real work is done by "\@newwordpair":
% This next line of code becomes
% "\(re)newcommand"\marg{cmd}"{\@ifstar"\dots.
%    \begin{macrocode}
\newcommand{\@newwordpair}[4]{%
   #1{#2}{\@ifstar
%    \end{macrocode}
% The "\@ifstar" checks if \meta{cmd} is called with or without a
% star and stores \meta{male} and \meta{female} in "\@eemeirM" and
% "\@eemeirF", respectively.  Then "\@eemeirword" is called to check
% for optional arguments and finish the job.
%    \begin{macrocode}
      {\def\@eemeirM{\MakeUppercase#3}%
       \def\@eemeirF{\MakeUppercase#4}%
       \@eemeirword}
      {\def\@eemeirM{#3}%
       \def\@eemeirF{#4}%
       \@eemeirword}}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@eemeirword}
% As promised, "\@eemeirword" picks up the optional argument to
% \meta{cmd}.  If "\ifmale"\meta{person} is undefined, it's because
% the user used \meta{cmd}\oarg{person} (something like "\E[pastor]")
% before setting the gender of \meta{person} with "\male"\oarg{person}
% or friends.  Doing so is really naughty of the user, and maybe I'm
% being too lenient letting Em get away with it by calling
% "\askforgender"\oarg{person} for Em.
%    \begin{macrocode}
\newcommand{\@eemeirword}[1][]{%
   \@ifundefined{ifmale#1}
      {\PackageWarning{eemeir}
         {You should set the #1 gender before using\MessageBreak it}%
       \askforgender[#1]}
      {\relax}%
%    \end{macrocode}
% If "\ifmale"\meta{person} is true, set the word stored before in
% "\@eemeirM"\@, otherwise use "\@eemeirF"\@.  Then use "\xspace" from
% the \textsf{xspace} package to insert a space if needed.
%    \begin{macrocode}
   \csname ifmale#1\endcsname\@eemeirM\else\@eemeirF\fi
   \xspace
}
%    \end{macrocode}
% \end{macro}
% \end{macro}\end{macro}
% \begin{macro}{\E}
% \begin{macro}{\Em}
% \begin{macro}{\Eir}
% \begin{macro}{\Eirs}
% Finally set up the commands that give this package its name
%    \begin{macrocode}
\newwordpair{\E}{he}{she}
\newwordpair{\Em}{him}{her}
\newwordpair{\Eir}{his}{her}
\newwordpair{\Eirs}{his}{hers}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}
% and set the main gender according to
% options.\nextlinelabel{ln:@eemeir}
%    \begin{macrocode}
\@eemeir
%</package>
%    \end{macrocode}
% \Finale