For questions and feedback please contact Alexander N. Schmidt-Lebuhn.
The Key2html tool was written to convert plain text dichotomous analytical keys into interactive HTML-based keys which can then be made available on the internet. The idea was not only to facilitate the conversion into HTML - which can be tiresome for a large number of taxa - but also to allow the navigation from couplet to couplet with hyperlinks, and eventually the navigation from terminal taxa of the current key to subkeys and database entries.
The program is made available for other researchers who would like to convert long, multiple, and/or interrelated keys. It has been tested successfully on keys of various formats and on Windows and Macintosh systems. Please note, however, that it is provided without any warranty or guarantee for its performance on your system. To use the advanced features (custom links), a basic understanding of URLs is needed.
1. |
Leaves ovate Leaves obovate Planta sylvatica |
2. |
Corolla yellow Planta arvensis Corolla white Planta vulgaris |
Note, however, that details like background colour, font type etc. are determined by the HTML file the table is inserted into, and also in part by the environment under which the page is shown, so that your results might differ from what you see here.
Analytical determination keys work like "choose your own adventure" stories, i.e., the reader has to answer a series of questions, taking a certain route through the key depending on the answers he gives, until he finally arrives at the taxon name or is given a reference to another (sub-)key. They are usually dichotomous, meaning that the questions have exactly two possible answers which should be direct opposites (good example: "leaves less than 10 mm long" vs. "leaves more than 10 mm long", bad example: "leaves less than 10 mm long" vs. "leaves serrate"). A pair of alternatives is called a couplet, each of the two alternatives a lead. The information provided after the leads, which can be either the name of a taxon, a reference to a subkey, or (most often) the number of the next couplet, is here called a direction.
There are two main types of keys: indented (yoked) and bracketed (parallel). Indented keys have the two leads of each couplet separated by the couplets following the first lead, so that it is easier to find the next "question". On the other hand, that makes it harder to compare the alternatives, especially in the first couplets of large keys. Bracketed keys keep the two leads of every couplet together, allowing for an easier comparison of the alternatives, but that means that only one of the next couplets follows in the text. It is also obvious that, in this case, the key cannot be navigated if the couplets are unnumbered, which would be possible in indented keys.
The keys produced by Key2html are always bracketed, for obvious reasons: only that format assures that both leads are displayed on the monitor at the same time, and the one disadvantage of bracketed keys - having to search for the following couplet - is taken care of by the HTML hyperlinks.
Your key has to conform to the following format if it is to be processed correctly:
12. two fertile stamens, two staminodes .. (Sanchezia) 13 - four fertile stamens .. 23Instead you should use this format:
12. two fertile stamens, two staminodes (Sanchezia) .. 13 - four fertile stamens .. 23
Submitting keys not conforming to these rules will yield strange results or none at all.
Make sure that JavaScript is activated in your browser. Copy and paste your key into the main text window of the Key2html form, set the correct options for your type of key (see below), click submit. A popup window should appear containing the HTML code for your navigatable key. You can select this code using your mouse pointer, copy and paste it into a text editor, and save it as an .html-file, or copy the part "<table ... </table>" into the appropriate position in the body of an existing .html file of your choice. If you want, you can now edit the layout in your text editor or in an HTML editor.
It is not recommended to place two interactive keys generated with Key2html in the same .html file because they will use the same identifiers for their couplets.
Unfortunately, it is rather difficult to program a computer so that it can reliably distinguish between all different types of keys. It is therefore not only necessary but also essential to set all options correctly, so that the program knows what to expect. Setting options not fitting the key will yield strange results or none at all.
"key is indented/yoked" vs. "key is bracketed"
Use this option to declare if your key is indented or bracketed.
Examples of indented keys:
1. Leaves ovate 2. Corolla yellow .. Planta arvensis 2*. Corolla white .. Planta vulgaris 1*. Leaves obovate .. Planta sylvatica
Leaves ovate Corolla yellow __ Planta arvensis Corolla white ___ Planta vulgaris Leaves obovate ______ Planta sylvatica
1. Leaves ovate 2 2. Corolla yellow Planta arvensis 2. Corolla white Planta vulgaris 1. Leaves obovate Planta sylvatica
It is assumed that bracketed keys always have directions to the next couplet. An example of a bracketed key:
1. Leaves ovate .. 2 1*. Leaves obovate .. Planta sylvatica 2. Corolla yellow .. Planta arvensis 2*. Corolla white .. Planta vulgaris
"leads start with numbers" vs. "only first lead has number" vs. "couplets are not numbered"
This option declares whether numbers (or letters) identify the couplets. If there are numbers, the script will read all characters from the first non-whitespace character of the paragraph to the next dot ("."), closing bracket (")"), star ("*"), or whitespace as the number. Dot, bracket, and star will be deleted. In bracketed keys, the selection of "not numbered" will be ignored; the key is then treated as having numbers at both leads. The number found at the first lead will be used to identify the couplet - take care that the directions match these numbers! -, but the number found at the second lead is irrelevant, so that the following keys are interpreted correctly:
1. Leaves ovate .. 2 - Leaves obovate .. Planta sylvatica 2. Corolla yellow .. Planta arvensis - Corolla white .. Planta vulgaris
1. Leaves ovate .. 2 1b. Leaves obovate .. Planta sylvatica 2. Corolla yellow .. Planta arvensis 2b. Corolla white .. Planta vulgaris
Use the option "only first lead" for the following type of key:
1. Leaves ovate .. 2 Leaves obovate .. Planta sylvatica 2. Corolla yellow .. Planta arvensis Corolla white .. Planta vulgaris
The following key will, as mentioned above, not work properly:
1a. Leaves ovate .. 2 1b. Leaves obovate .. Planta sylvatica 2a. Corolla yellow .. Planta arvensis 2b. Corolla white .. Planta vulgaris
"taxa are numbered" vs. "taxa are not numbered"
In some publications, taxa are numbered to facilitate finding them in the main text. Key2html will treat these numbers as a part of the taxon name if "not numbered" is selected, and delete all characters before the first whitespace in the direction text from the resulting interactive key if "numbered" is selected. You should definitely avoid selecting "numbered" if your taxa are not. This is what the option is about:
1. Leaves ovate .. 2 -. Leaves obovate .. 1. Planta sylvatica 2. Corolla yellow .. 2. Planta arvensis -. Corolla white .. 3. Planta vulgaris
Treatment of taxa and the special character "|"
In many cases, the terminal taxa/identifications found in the key can remain plain text, so that the user will only get a name. On the other hand, it is possible that you might want to have hyperlinks to subkeys, for example from a key to the genera of a family to separate generic keys.
Therefore Key2html provides some ways to generate hyperlinks from the taxon names. The most simple is to check the option "link all taxa to synonymous .html files". The typical situation would be that you have a key to genera, with taxa like "Lycopodium" as the terminal direction of the key, which you then want to link to a key to the species of, in this case, Lycopodium, in the same directory. The script would then produce a hyperlink to "Lycopodium.html". In converting the names, spacers will be converted to "_", and dots and round brackets will be ignored, so that a taxon name like "Planta vulgaris var. vulgaris (L.) DC." will link to "Planta_vulgaris_var_vulgaris_L_DC.html". A second popup window will appear and explicitly list all links that have been generated, so that you know how the subkey files have to be named.
The next two options are more difficult, but all the more powerful. "Link all taxa with custom link" will use the text entered in the "custom link text" field to produce hyperlinks. You have to insert the character "|" together with a following number into the text field, so that the script knows where to insert the taxon name. "|0" means the whole name, so that the custom link "http://www.whatever.org/|0.html" would result in "http://www.whatever.org/Lycopodium.html" or "http://www.whatever.org/Planta_vulgaris_var_vulgaris_L_DC.html" according to our both examples. "|1", "|2" and higher numbers refer to the single elements of complex names as separated by spacers. This allows you to construct links that use parts of the taxon name as parameters. In our second example, "|1" would refer to "Planta", "|3" to "var". "http://www.google.com/search?q=|1+|2" will start Google searches for the first two parts of the taxon names when they are clicked.
The other option, "decide individually", works like the previous if you only enter a custom link into the field "default link text" and change nothing else. The real difference lies in the three "individual link text" fields, where you can also enter link texts with "| plus number" commands, so that up to four different link types can be generated for one key. To indicate where the different types should be applied, taxon names must start with "|1", "|2", or "|3" in your submitted key. All taxa not starting with "|" will be treated by default; if the "default link text" is empty, they will remain as plain text. The following is a typical situation where this would be useful with individual link text #1 linking to files on the species (e.g., "speciesdata\|0.html") and link text #2 linking to a subkey (e.g., "|7_subkey.html"):
1. Leaves ovate .. 2 - Leaves obovate .. |1Planta sylvatica 2. Corolla yellow .. |1Planta arvensis - Corolla white .. |2Key to the varieties of Planta vulgaris
The text field "additional link options" can be used to customize the generated links using the parameters of the <a> tag of HTML. An example would be 'target="_blank"', a command forcing the browser to open the links in new windows. The option influences all links that are generated for terminal taxa.