summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/shipunov/doc/biokey-doc-en.tex
blob: 26dd3625d7679c2ff4ff2e3f0ea7f11af33db581 (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
\documentclass{article}
\usepackage[bookmarks=false,colorlinks=true,hypertexnames=false]{hyperref}
\usepackage{biokey}

\author{A.\,Shipunov\footnote{e-mail: \texttt{dactylorhiza at gmail}}}
\title{\texttt{biokey}, the package for precious and flexible identification keys}
\date{}

\begin{document}
\maketitle

This package can be used for creating biological identification keys. Different layouts are available.

\section{General usage}

This is the textual key:

\begin{verbatim}
1. It is an animal ... 2.
-  It is a plant ... 3.
2. It is spiny ... Hedgehog
-  It is not very spiny ... Swift
=  It is not spiny at all ... Siskin
3(1). Lots of wood ... Spruce
- No wood ... Daisy
\end{verbatim}

The interpretation in suggested language is follows:

\bigskip\hrule

\begin{verbatim}

\begin{biokey}

\Z1. It is an animal \T 2.

\AN  It is a plant \T 3.

\Z2. It is spiny \TT Hedgehog

\AN  It is not very spiny \TT Swift

\AAN  It is not spiny at all \TT Siskin

\ZZ3(1). Lots of wood \TT Spruce

\AN No wood \TT Daisy

\end{biokey}

\end{verbatim}

\hrule\bigskip

\begin{biokey}

\Z1. It is an animal \T 2.

\AN  It is a plant \T 3.

\Z2. It is spiny \TT Hedgehog

\AN  It is not very spiny \TT Swift

\AAN  It is not spiny at all \TT Siskin

\ZZ3(1). Lots of wood \TT Spruce

\AN No wood \TT Daisy

\end{biokey}

\bigskip\hrule\bigskip

For aesthetics, I recommend that text before \verb|\T| should not end with dot (with the exception of abbreviations). \verb|\T| and \verb|\TT| are just the same thing, but second is better to designate names, and first is better for numbers. Sometimes, these two commands cannot format the paragraph without overfulls, in these (rare) cases I recommend the \verb|\TTTT| or ``old-style'' \verb|\TTT| which results are less precious but require less handwork.

\verb|\Z| and \verb|\ZZ| are different only for the second is used for backreferences, or for typical in serial zoological keys references for theses and antitheses. These two commands along with \verb|\AN|, \verb|\AAN|, and (not used in the example above) \verb|\AAAN| are used also for aesthetic hanging indentation.

Commands \verb|\N|, \verb|\NN| and \verb|\NNN| are for end-level objects (species, for example). They did not produce leading dots, but justify following object right, next with some space, or on next line, respectively.

Command \verb|\VT| is for hanging number references. There is also starred variant, \verb|\VT*|, where dot leader are also protruding outside right text margin.

By default, all \verb|\T|-like commands along with \verb|\N| and \verb|\NN| have the declaration \verb|\samepage| inside. One can redefine that via \verb|\SameDecl| hook. The most obvious redefinition is \verb|\relax|.

\verb|\SHRIFTZ| and \verb|\SHRIFTN| are two hooks which are defined by default as \verb|\relax| (do nothing), so one can redefine them to change the representation of these number and end-level objects, respectively. For example, 

\verb|\renewcommand{\SGRIFTZ}{\textbf}| 

will result in boldface theses numbers.

Several commands designed for commentaries after theses (or antitheses). \verb|\FK| put the text in footnote size, \verb|\KOM| imitate these, but without number, and \verb|\VPRAVO| aligned its contents to the right. \verb|\OTSTUP| is a hook for indentation of first two kinds of comments. By default it is 2\,em, but one can easily redefine it.

\section{``Automatic'' keys}

This sort of key can put numbers automatically. The example (needs two \LaTeX\ runs):

\bigskip\hrule

\begin{verbatim}

\begin{biokey}

\TE{ani} It is an animal \SS{spi}

\AN  It is a plant \SS{pla}

\TE{spi} It is spiny \TT Hedgehog

\AN  It is not very spiny \TT Swift

\AAN  It is not spiny at all \TT Siskin

\SE{pla}{ani} Lots of wood \TT Spruce

\AN No wood \TT Daisy

\end{biokey}

\end{verbatim}

\hrule\bigskip

\begin{biokey}

\TE{ani} It is an animal \SS{spi}

\AN  It is a plant \SS{pla}

\TE{spi} It is spiny \TT Hedgehog

\AN  It is not very spiny \TT Swift

\AAN  It is not spiny at all \TT Siskin

\SE{pla}{ani} Lots of wood \TT Spruce

\AN No wood \TT Daisy

\end{biokey}

\bigskip\hrule\bigskip

The biggest advantage of this type of key is that it is much easier to correct. It is possible to convert ``ordinary'' key to ``automatic'' key and further to HTML, with the help of \texttt{biokey2html} scripts (see documentation). See also how hyper-references working here.

\section{Indented keys}

And, finally, the different key layout---so-called indented keys:

\bigskip\hrule

\begin{verbatim}

\begin{biokey}

\Z A. It is an animal

\begin{LE}

\Z AA. It is more or less spiny

\begin{LE}[2]

\Z AAA. It is very spiny \TT Hedgehog

\Z BBB.  It is not very spiny \TT Swift

\end{LE}

\Z BB. It is not spiny at all \TT Siskin

\end{LE}

\Z B. It is a plant

\begin{LE}

\Z CC. Lots of wood \TT Spruce

\Z DD. No wood \TT Daisy

\end{LE}

\end{biokey}

\end{verbatim}

\hrule\bigskip

\begin{biokey}

\Z A. It is an animal

\begin{LE}

\Z AA. It is more or less spiny

\begin{LE}[2]

\Z AAA. It is very spiny \TT Hedgehog

\Z BBB.  It is not very spiny \TT Swift

\end{LE}

\Z BB. It is not spiny at all \TT Siskin

\end{LE}

\Z B. It is a plant

\begin{LE}

\Z CC. Lots of wood \TT Spruce

\Z DD. No wood \TT Daisy

\end{LE}

\end{biokey}

\bigskip\hrule\bigskip

It is more complicated then previous examples, so one may to consider \texttt{dichokey} package, but it is much less flexible.

\end{document}