summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/biocon/biocon.nw
blob: 7505700a78c51db93971047e9e74f047b2779d36 (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
\documentclass{article}
\usepackage{noweb}
\usepackage{hyperref}
\usepackage[a4paper,margin=1.5cm]{geometry}

\newcommand{\biocon}{\texttt{biocon}}

\title{The \biocon\ package}
\author{Pieter Edelman}

\bibliographystyle{plain}

\begin{document}
@
\maketitle

\begin{abstract}
The \biocon\ package handles the typesetting of scientific species names. There are different modes of showing these names. Multiple occurances in the same document are taken care of.
\end{abstract}
\tableofcontents
\section{The built-up of the package}
According to \cite{Goossens1994}, each package foolows a standard built-up, which is:
<<biocon.sty>>=
<<Identification part>>
<<Declaration of options>>
<<Execution of options>>
<<Package loading>>
<<Main code>>
@
The identification part is easy. This package is designed exclusively for \LaTeXe, and it provides the \biocon\ package.
<<Identification part>>=
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{biocon}[2001/08/18]
@
\section{The user interface}
\subsection{Brief syntax}
<<Main code>>=
<<Declarations>>
<<The user interface>>
<<Internal workings>>
@
The \biocon\ package automates the process of typesetting biological species names. Different conventions are followed for animals, bacteria, plants and fungi (the latter two follow the same conventions). These four main groups are used in this package. The amount of information the user provides is variable, for example the user should be able to typeset the full name with genus, old genus, author etc., but also just the normal binomial name.

Two kinds of commands are provided to reach this goal, the first is for quick-n-dirty use-only-once names. The other is a set of commands were first the species is declared, and then used throughout the document.

The quick-n-dirty commands look like:
\begin{itemize}
  \item\verb!\plantlike [!\textit{how}\verb!]{!\textit{parameters}\verb!}!
  \item\verb!\funguslike[!\textit{how}\verb!]{!\textit{parameters}\verb!}!
  \item\verb!\animallike[!\textit{how}\verb!]{!\textit{parameters}\verb!}!
  \item\verb!\bactlike  [!\textit{how}\verb!]{!\textit{parameters}\verb!}!
\end{itemize}

The declaration commands look like:
\begin{itemize}
  \item\verb!\newplant {!\textit{identifier}\verb!}{!\textit{parameters}\verb!}!
  \item\verb!\newfungus{!\textit{identifier}\verb!}{!\textit{parameters}\verb!}!
  \item\verb!\newanimal{!\textit{identifier}\verb!}{!\textit{parameters}\verb!}!
  \item\verb!\newbact  {!\textit{identifier}\verb!}{!\textit{parameters}\verb!}!
\end{itemize}

Declarated species can be used with
\begin{itemize}
  \item\verb!\plant [!\textit{how}\verb!]{!\textit{identifier}\verb!}!
  \item\verb!\fungus[!\textit{how}\verb!]{!\textit{identifier}\verb!}!
  \item\verb!\animal[!\textit{how}\verb!]{!\textit{identifier}\verb!}!
  \item\verb!\bact  [!\textit{how}\verb!]{!\textit{identifier}\verb!}!
\end{itemize}

In these commands, \textit{parameters} define the actual species. They can consist of genus, oldgenus, epithet, oldepithet, author, year, oldauthor, and oldyear, and follow a \verb!key=value! syntax. Furthermore, more parameters can be defined by the user. The \textit{identifier} is the identifier by which a species is recognized by the user. The commands to declare species are discussed below, while the commands to use them are discussed later.

The declaration commands are all piped through a single command. The quick-n-dirty commands also declare a new species, but always with the same identifier. This command is the \verb!\n@wsp@cies{!\textit{type}\verb!}{!\textit{identifier}\verb!}{!\textit{parameters}\verb!}! command, where \textit{type} is P, F, A, B for plant, fungus, animal or bacterium.
\subsection{The implementation for the declaration part}
As described above, all the declaration commands are piped through a single command (the quick-n-dirty commands don't get a \textit{type} identifier, only a single identifier is needed):
<<The user interface>>=
\newcommand{\newplant}[2]{\n@wsp@cies{P}{#1}{#2}}
\newcommand{\newfungus}[2]{\n@wsp@cies{F}{#1}{#2}}
\newcommand{\newanimal}[2]{\n@wsp@cies{A}{#1}{#2}}
\newcommand{\newbact}[2]{\n@wsp@cies{B}{#1}{#2}}

\newcommand{\plantlike}[2][]
  {\n@wsp@cies{}{Q@D}{#2}\plant[#1]{Q@D}\expandafter\Q@DCleanup\Q@DCleanList+}
\newcommand{\funguslike}[2][]
  {\n@wsp@cies{}{Q@D}{#2}\fungus[#1]{Q@D}\expandafter\Q@DCleanup\Q@DCleanList+}
\newcommand{\animallike}[2][]
  {\n@wsp@cies{}{Q@D}{#2}\animal[#1]{Q@D}\expandafter\Q@DCleanup\Q@DCleanList+}
\newcommand{\bactlike}[2][]
  {\n@wsp@cies{}{Q@D}{#2}\bact[#1]{Q@D}\expandafter\Q@DCleanup\Q@DCleanList+}
@
\section{The internal workings}
For now, we ignore the commands to use the declared species, and instead define the internal workings of the \verb!\n@wsp@cies! command.

Since the \verb!key=value! syntax is used, the \texttt{keyval} package is needed:
<<Package loading>>=
\RequirePackage{keyval}
@
The \verb!\n@wsp@cies! command creates a command for all the different parameters it gets, which name is of \textit{TypeIdentifier@Parametername}, for example, if the command would be \verb!\n@wsp@cies{A}{Hs}{genus=homo,epithet=sapiens}!, it would define the commands \verb!\AHs@genus! and \verb!\AHs@epiteth!.
<<Internal workings>>=
<<The n@wsp@cies command>>
@
<<The n@wsp@cies command>>=
\newcommand{\n@wsp@cies}[3]{%
@
First this function determines what the first part of all the commands should be. It stores this in a parameter called \verb!\curr@ntid!.
<<Declarations>>=
\newcommand{\curr@ntid}{}
@
<<The n@wsp@cies command>>=
\renewcommand{\curr@ntid}{#1#2@}%
@
This command also adds a counter with name \textit{Curr@ntID}\verb!counter!, which will be used to track whether this command has been used before (0 for no, 1 for yes) (for Q@D an exception is made).
<<Declarations>>=
\newcounter{Q@D@counter}
@
The \verb!\n@wsp@cies! command uses the \texttt{ifthen} package.
<<Package loading>>=
\RequirePackage{ifthen}
@
<<The n@wsp@cies command>>=
\ifthenelse{\equal{#2}{Q@D}}%
  {\relax}%
  {\newcounter{\curr@ntid counter}}%
\setcounter{\curr@ntid counter}{0}%
@
Then it goes forth by processing all the parameters. According to \cite{Carlisle1999}, for every key an apart function should exist. For the quick-n-dirty commands a \verb!\Q@DCleanList! command is created to which holds all the possible keys with \verb!\relax! associated. The \verb!\Q@DCleanup! commands sets these keys (this is to prevent old values from being used when a value is not given).
<<Internal workings>>=
<<The key=value functions>>
@
<<The key=value functions>>=
\def\Q@DCleanup#1+{\n@wsp@cies{}{Q@D}{#1}}

\newcommand{\add@species@key}[2]{%
  \define@key{SpeciesParams}{#1}{#2}
  \expandafter\ifx\csname Q@DCleanList\endcsname\relax%
     \def\Q@DCleanList{#1=\relax}%
  \else%
     \edef\Q@DCleanList{\Q@DCleanList,#1=\relax}%
  \fi%
}
@
<<The n@wsp@cies command>>=
\setkeys{SpeciesParams}{#3}%
}
@
The handler for the genus should make sure it is written capitalized. Therefore a function is made which splits the first letter of a word. It used more often in this package.
<<Declarations>>=
\newcommand{\T@mpFirst}{}
\newcommand{\T@mpRest}{}
<<The key=value functions>>=
\def\SplitG@nusL@tters(#1#2){%
  \uppercase{\renewcommand{\T@mpFirst}{#1}}\lowercase{\renewcommand{\T@mpRest}{#2}}}
@
Then the genus is processed and stored in the right way.
<<The key=value functions>>=
\add@species@key{genus}{%
  \SplitG@nusL@tters(#1)%
  \expandafter\edef\csname\curr@ntid genus\endcsname{\T@mpFirst\T@mpRest}%
}
@
Of course, this also goes for the old genus.
<<The key=value functions>>=
\add@species@key{oldgenus}{%
  \SplitG@nusL@tters(#1)%
  \expandafter\edef\csname\curr@ntid oldgenus\endcsname{\T@mpFirst\T@mpRest}%
}
@
The epithet and old epithet all have to be completely lowercase.
<<The key=value functions>>=
\add@species@key{epithet}{\lowercase{\expandafter\edef\csname\curr@ntid epithet\endcsname{#1}}}
\add@species@key{oldepithet}{\lowercase{\expandafter\edef\csname\curr@ntid oldepithet\endcsname{#1}}}
@
And there are the author, old author year and the old year.
<<The key=value functions>>=
\add@species@key{author}{\expandafter\edef\csname\curr@ntid author\endcsname{#1}}
\add@species@key{year}{\expandafter\edef\csname\curr@ntid year\endcsname{#1}}
\add@species@key{oldauthor}{\expandafter\edef\csname\curr@ntid oldauthor\endcsname{#1}}
\add@species@key{oldyear}{\expandafter\edef\csname\curr@ntid oldyear\endcsname{#1}}
@
As mentioned, the user should also be able to add own taxonomical structures. Herefore a the \verb!\newtaxon{!\textit{name}\verb!}! is used.
<<Internal workings>>=
\newcommand{\newtaxon}[1]{\add@species@key{#1}{\expandafter\edef\csname\curr@ntid #1\endcsname{##1}}}
@
Two special keys are for the default full style and the default abbreviation.
<<The key=value functions>>=
\define@key{SpeciesParams}{fullstyle}
  {\expandafter\def\csname\curr@ntid fullstyle\endcsname{\csname Sp@cies#1\endcsname}}
\define@key{SpeciesParams}{abbrstyle}
  {\expandafter\def\csname\curr@ntid abbrstyle\endcsname{\csname Sp@cies#1\endcsname}}
@
\subsection{The implementation for the use part part}
There's a lot to do with the actual showing of a species. This package was born from the the desire to automagically show \textit{Genus epithet} the first time a species was used, but us \textit{G. epithet} all subsequent times. However, sometimes an abbreviation should just be \textit{Genus}, and someimes the full name is required. Even more, writing the complete species names with subspecies and old genus stuff etc. is better left to the computer. By default, four different modes of typesetting are provided; the \textit{how} parameter specifies how the name should be typeset, this can be \textbf{e}xtended, which gives all available information, \textbf{l}ong, which gives genus and epithet, \textbf{a}bbreviated, which gives the first letter of the genus followed by the epithet, and \textbf{g}enus, which gives the genus only. It is also possible for the user to create typesetting schemes, and to set the default full name and abbreviation per species or globally.

Let's start with the commands used to write out the names stored in \LaTeX' memory. These are accesible by the user and are already discussed:
\begin{itemize}
  \item\verb!\plant [!\textit{how}\verb!]{!\textit{identifier}\verb!}!
  \item\verb!\fungus[!\textit{how}\verb!]{!\textit{identifier}\verb!}!
  \item\verb!\animal[!\textit{how}\verb!]{!\textit{identifier}\verb!}!
  \item\verb!\bact  [!\textit{how}\verb!]{!\textit{identifier}\verb!}!
\end{itemize}
These command use ``style'' commands to do the actual typesetting. A ``style'' command contains text and \\\verb!\taxon{!\textit{pre}\verb+!+\textit{name}\verb+!+\textit{post}\verb!}! commands. Text is shown verbatim. The \verb!\taxon! command shows the taxon \textit{name} for the current species enclosed by \textit{pre} and \textit{post} if this taxon exists. So the typesetting is done by \verb!\plant!/\verb!Fungus!/\verb!Animal!/\verb!Bact!$\rightarrow$\textit{style command}$\rightarrow$\verb!\taxon!. Besides the \verb!Taxon! command, there is a similar \verb!FirstTaxon! command, which shows only the first letter of that taxon.
<<Internal workings>>=
<<The Taxon commands>>
@
Both the \verb!\taxon! and the \verb!\taxonfirst! command pipe through a single \verb!\Sh@wTax@n! command, which takes its argument in the form of \verb!+(!\textit{pre}\verb.!.\textit{name}\verb.!.\textit{post}\verb!)+!\textit{how}\verb!+!. The unique enclosures are needed to prevent interference with the \textit{pre} and \textit{post} from the user. \textit{how} is either \textit{n} for normal or \textit{a} for abbreviated (first letter only).
@
<<The Taxon commands>>=
\newcommand{\taxon}[1]{\Sh@wTax@n+(#1)+n+}
\newcommand{\taxonfirst}[1]{\Sh@wTax@n+(#1)+a+}

\def\Sh@wTax@n+(#1!#2!#3)+#4+{%
@
\verb!\curr@ntid! is the ID of the species currently treated. This will be discussed later.
<<The Taxon commands>>=
  \expandafter\ifx\csname\curr@ntid#2\endcsname%
    \relax%
@
If the taxon exist, the function checks if it should display normal, and if this is the case it should display \textit{pre}, the taxon, and \textit{post}.
<<The Taxon commands>>=
  \else%
    \ifthenelse{\equal{#4}{n}}{%
      #1\csname\curr@ntid#2\endcsname#3%
@
Otherwise, only the first letter should be displayed. This is done by expanding the current taxon into the macro \verb!\T@mpTax@n! which is used as argument for the lettersplitting function.
<<The Taxon commands>>=
    }{%
      \edef\T@mpTax@n{\csname\curr@ntid#2\endcsname}%
      #1\expandafter\Sh@wFirst\T@mpTax@n+#3%
    }%
  \fi%
}

\def\Sh@wFirst#1#2+{#1}
@
New style can be created with the \verb!\newtaxastyle{!\textit{name}\verb!}{!\textit{style}\verb!}! command, where \textit{name} is an identifier for that style, and \textit{style} is, well, the style.
<<The user interface>>=
<<The newtaxastyle command>>
@
<<The newtaxastyle command>>=
\newcommand{\newtaxastyle}[2]{\expandafter\def\csname Sp@cies#1\endcsname{#2}}
@
It is often the case that some names should be printed in italics if the rest of the text is upright, or vice versa. Herefore the command \verb!\taxit{}! is provided, which is the same as \verb!\em! in \verb!latex.ltx!.
<<Internal workings>>=
\DeclareRobustCommand\taxitalics
        {\@nomath\em \ifdim \fontdimen\@ne\font >\z@
                       \upshape \else \itshape \fi}
\DeclareTextFontCommand{\taxit}{\taxitalics}
@
Using this, the default type can be implemented.
<<Internal workings>>=
\newtaxastyle{ePlant}
  {\taxit{\taxon{!genus!}\taxon{ !epithet!}}\taxon{ (!oldauthor!)}\taxon{ !author!}}
\newtaxastyle{eAnimal}
  {\taxit{\taxon{!genus!}\taxon{ (!oldgenus!)}\taxon{ !epithet!}}\taxon{ (!oldauthor!}%
   \taxon{, !oldyear!)}\taxon{!author!}\taxon{, !year!}}
\newtaxastyle{f}
  {\taxit{\taxon{!genus!}\taxon{ !epithet!}}}
\newtaxastyle{a}
  {\taxit{\taxonfirst{!genus!.}\taxon{ !epithet!}}}
\newtaxastyle{g}
  {\taxit{\taxon{!genus!}}}
@
Now the default styles can be set.
<<Declarations>>=
\newcommand{\Gl@balF@llStyle}{}
\newcommand{\Gl@bal@bbrStyle}{}
\newcommand{\Gl@balPE@llStyle}{}
\newcommand{\Gl@balFE@llStyle}{}
\newcommand{\Gl@balAE@llStyle}{}
\newcommand{\Gl@balBE@llStyle}{}
@
<<The user interface>>=
\newcommand{\defaultplante}[1]
  {\renewcommand{\Gl@balPE@llStyle}{\csname Sp@cies#1\endcsname}}
\newcommand{\defaultfunguse}[1]
  {\renewcommand{\Gl@balFE@llStyle}{\csname Sp@cies#1\endcsname}}
\newcommand{\defaultanimale}[1]
  {\renewcommand{\Gl@balAE@llStyle}{\csname Sp@cies#1\endcsname}}
\newcommand{\defaultbacte}[1]
  {\renewcommand{\Gl@balBE@llStyle}{\csname Sp@cies#1\endcsname}}
\newcommand{\defaultfull}[1]
  {\renewcommand{\Gl@balF@llStyle}{\csname Sp@cies#1\endcsname}}
\newcommand{\defaultabbr}[1]
  {\renewcommand{\Gl@bal@bbrStyle}{\csname Sp@cies#1\endcsname}}
@
<<Internal workings>>=
\defaultplante{ePlant}
\defaultfunguse{ePlant}
\defaultanimale{eAnimal}
\defaultbacte{eAnimal}
\defaultfull{f}
\defaultabbr{a}
@
The calling commands fisrt set \verb!\curr@ntid! to the current ID (duh!). Furthermore, they have a decision tree: if no style is provided, then it is determined whether or not this is the first use in the document, and action is taken appropiately. This is all done using the \verb!\sh@wsp@cies{!\textit{type}\verb!}{!\textit{ID}\verb!}{!\textit{how}\verb!}!.
<<The user interface>>=
<<The calling commands>>
@
<<The calling commands>>=
\newcommand{\plant}[2][]{\sh@wsp@cies{P}{#2}{#1}}
\newcommand{\fungus}[2][]{\sh@wsp@cies{F}{#2}{#1}}
\newcommand{\animal}[2][]{\sh@wsp@cies{A}{#2}{#1}}
\newcommand{\bact}[2][]{\sh@wsp@cies{B}{#2}{#1}}
@
First, the command sets \verb!\curr@ntid! (if it's Q@D no \textit{type} should be set).
<<Internal workings>>=
<<The sh@wsp@cies command>>
@
<<The sh@wsp@cies command>>=
\newcommand{\sh@wsp@cies}[3]{%
  \ifthenelse{\equal{#2}{Q@D}}%
    {\renewcommand{\curr@ntid}{#2@}}%
    {\renewcommand{\curr@ntid}{#1#2@}}%
@
Then there is checked for a provided style.
<<The sh@wsp@cies command>>=
  \ifthenelse{\equal{#3}{}}{%
    \ifnum\value{\curr@ntid counter}=0%
@
If this is not the case, it is checked whether this is the first time the species is used. Of it is, for default full style is checked and used.
<<The sh@wsp@cies command>>=
      \setcounter{\curr@ntid counter}{1}%
      \expandafter\ifx\csname\curr@ntid fullstyle\endcsname\relax%
        \csname Gl@balF@llStyle\endcsname%
      \else%
        \csname\curr@ntid fullstyle\endcsname %
      \fi%
@
Otherwise, the default abbreviation is checked and used.
<<The sh@wsp@cies command>>=
    \else%
      \expandafter\ifx\csname\curr@ntid abbrstyle\endcsname\relax%
        \csname Gl@bal@bbrStyle\endcsname%
      \else%
        \csname\curr@ntid abbrstyle\endcsname%
      \fi%
    \fi%
@
If a style is provided, use this style. If this style is ``extended'', select the appropiate style for the kingdom.
<<The sh@wsp@cies command>>=
  }{%
    \ifthenelse{\equal{#3}{e}}{%
      \csname Gl@bal#1E@llStyle\endcsname%
    }{%
      \csname Sp@cies#3\endcsname%
    }%
  }%
}
@
\bibliography{literature}
\end{document}