summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/biocon/manual.tex
blob: cb03bace113b981df1e7b3770e60201c2776b1f3 (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
\documentclass{article}
\usepackage{biocon}
\newtaxon{strain}
\newplant{At}{genus=Arabidopsis,epithet=thaliana,author=Heynh.,oldauthor=L.,strain=1100}
\newtaxastyle{WithStrain}{\taxit{\taxonfirst{!genus!.}\taxon{ !epithet!}}\taxon{ \#!strain!}}
\usepackage{hyperref}
\usepackage{ulem}
\usepackage{verbatim}
\makeatletter
\newenvironment{breakverbatim}{\def\@xobeysp{\ }\verbatim}{\endverbatim}
\makeatother

\bibliographystyle{plain}

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

\begin{document}
\maketitle
\tableofcontents

\begin{abstract}
The \biocon---biological conventions--- package aids the typesetting of some biological conventions. At the moment, it does a good job at typesetting species names (and ranks below the species level). A distinction is made between the Plant, Fungi, Animalia and Bacteria kingdom. The species names are typeset in a default way but can be customized. Different default styles are used in different situations.  
\end{abstract}
\section{Introduction}
The correct typesetting of biological species and ranks below species follows some strict rules, which are sometimes hard to remember for ``average'' users. Even worse, animals, bacteria, and plants and fungi follow different rules, as described in \cite{Animals}, \cite{Bacteria}, \cite{Plants}. However, throughout normal texts more simple rules are used. 

A little example: ``Thale Cress'', a small plant which is often used by plant molecular biologists, should be written as ``\plant[e]{At}''. Every species consists of the capitalized name of the genus to which the species belongs (\plantlike{genus=arabidopsis}), followed by a species-specific epithet (\taxit{thaliana}). For plants, this should be followed by the name of the author who described the plant (Heynh.). However, this plant was first described with a different name by Linnaeus, who created this system (which has changed a lot ever since), so this name should be included in parentheses (L.). It is common use to write the taxa capitalized.

However, if I were to write a paper about this plant, I would just write \plant{At} the first time, and in further occurances \plant{At} or, since it is such a common used plant, \plant[g]{At}. Only in the ``material and methods'' section, the exact name is written. But here also the ecotype and possible strain or batch should be included in the name. Pfff.... 

The \biocon\ package simplifies this typesetting and ensures a consistent writing of the names throughout a document.
\section{Simple use}
Like all packages, this package can be loaded by typing \verb!\usepackage{biocon}! in the preamble of the document. There are no options which can be passed to the package here.

The package provides the command pairs \verb!\newplant! \& \verb!\plant!, \verb!\newfungus! \& \verb!\fungus!, \verb!\newanimal! \& \verb!\animal!, \verb!\newbact! \& \verb!\bact! for often used species, and similar \verb!\plantlike!, \verb!\funguslike!, \verb!\animallike!, \verb!\bactlike! for single-time uses.

The commands starting with \verb!\New! are used to describe a species, and take the following arguments \{\textit{identifier}\}\{\textit{parameters}\}. \textit{Identifier} is an unique string consisting of alphanumeric characters to describe the species (e.g. \textit{At}). \textit{Parameters} are the parameters which make up the species name, as \texttt{key=value} pairs. The standard keys are \textit{genus, oldgenus, epithet, author, oldauthor, year, oldyear}. See section~\ref{sec:Power use} on how to add more taxa. For example, the command to specify \plant{At} was:\begin{breakverbatim}\newplant{At}{genus=Arabidopsis,epithet=thaliana,author=Heynh.,oldauthor=L.}\end{breakverbatim}

The commands to use them take the arguments [\textit{how}]\{\textit{identifier}\}. \textit{how} is how the species can be typeset, and this is by default ``e'' (\textbf{e}xtended) for the complete name with author and all that stuff, ``f'' (\textbf{f}ull) for the simple \textit{Genus epithet} form, ``a'' (\textbf{a}bbreviated) for the \textit{G. epithet} form, or ``g'' (\textbf{g}enus) for \textit{Genus}. If \textit{how} is not specified, it defaults to ``full'' the first time it is used, and ``abbreviated'' on any subsequent occasion. In section~\ref{sec:Power use} it is explained how custom styles can be created and default style can be set.

The commands ending on \verb!Like! are a mixture between the declaration and the using commands. They take the arguments [\textit{how}]\{\textit{parameters}\}, which are the same as described above. These commands are for species which are used a single time.

\section{Power use \texttt{;-)}}\label{sec:Power use}
Of course this is vastly exaggerated, but the package is quite configurable. The user can create new taxa, new styles, set the default full-and abbreviation styles globally, or for each species individually.

New taxa are generated by the \verb!\newtaxon! command. It takes the name of the new taxon as its argument, after which it can be used as any other taxon in the parameter list of the species commands.

Of course, they also have to be able to used somewhere. This can be done with the \verb!\newtaxastyle! command. It takes \{\textit{name}\}\{\textit{style}\} as its arguments. \textit{Name} is an unique string of alphanumeric characters that functions as the name of the style. The \textit{style} is made up of text and \verb!\taxon! and \verb!\taxonfirst! commands. These are essentially the same commands which check whether the specified taxon exists, and if it does writes out the specified taxon and the specified text around it. \verb!TaxonFirst! writes only the first letter. These commands take the argument\{\textit{pre}!\textit{taxon}!\textit{post}\}. Often it is required that the taxa are written in italics, except when the surrounding text is in italics. For this the \verb!\taxit! command is provided, which is shamelessly copied verbatim from the \verb!\emph! command from \texttt{latex.ltx}. \emph{Don't use \texttt{emph} for this, for this is provided for emphasizing text, and this can be modified (as it is here).} For example, suppose I want to add a strain number to \plant{At}. I can do this by \verb!\newtaxon{strain}!. Then a new style which looks like the abbreviated style but with the strain number appended can be defined using \begin{breakverbatim}\newtaxastyle{WithStrain}{\taxit{\taxonfirst{!genus!.}\taxon{ !epithet!}}\#\taxon{ !strain!}}\end{breakverbatim}
Then, if the original \verb!\newplant! command was \begin{breakverbatim}\newplant{At}{genus=Arabidopsis,epithet=thaliana,author=Heynh.,oldauthor=L.,strain=1100}\end{breakverbatim} 
the command \verb!\plant[WithStrain]{At}! produces \plant[WithStrain]{At}.

It is possible to set default styles for extended name, full name and for abbreviation. To do this globally, the commands \verb!\defaultplante!, \verb!\defaultfunguse!, \verb!\defaultanimale!, \defaultbacte!, \verb!\defaultfull! and \verb!\defaultabbr! are provided. They take as its argument the name of a style, which  can be a default style\footnote{The default extended styles for are called ``ePlant'' for plants and fungi, and ``eAnimal'' for animals and bacteria. See also section~\ref{sec:Bugs etc.}} or a created style. Furthermore, the keys \verb!abbrstyle! and \verb!fullstyle! can be used in the parameter list of the commands, to set these styles specific for the species.

\section{Bugs, errors and everything else you don't want in a package}\label{sec:Bugs etc.}
This package is probably not free of bugs. If you find any behavior you don't expect, please let \href{mailto:P.Edelman@gmx.net}{me} know (even if you think you don't understand the working of the package, in that case this manual is not good enough). \emph{This version of the \biocon\ package is not backwards compatible with the old version. You can still grab the old version from CTAN.}

Furthermore, I am a biologist (to-be), but my taxonomy knowledge is limited to the basics. Chances are that the styles I provided are not entirely correct (especially for the bacteria I don't know the official typesetting rules). If you know better please let \href{mailto:P.Edelman@gmx.net}{me} know. One thing still, if you think that there are some options which should be absolutely included, you can also let \href{mailto:P.Edelman@gmx.net}{me} know.

Pieter Edelman\\
\href{mailto:P.Edelman@gmx.net}{P.Edelman@gmx.net}

\section{Links}
\subsection{Information on taxonomy}
By far the most entertaining site on taxonomy is IMHO \href{http://www.best.com/~atta/taxonomy.html}{Curiosities of Biological Taxonomy}.
\subsection{Other \LaTeX\ packages}
\begin{itemize}
  \item\href{http://www.ctan.org/tex-archive/macros/latex/contrib/supported/dichokey/}{dichokey} Construct dichotomous identification keys.
  \item\href{http://www.ctan.org/tex-archive/macros/latex/contrib/supported/texshade/}{texshade} Package for setting nucleotide and peptide alignments.
\end{itemize} 
\bibliography{literature}
\end{document}