Electronic Field Guide Project
Key Author Instructions
I. Generalities specialized to keys made by systemitists or field naturalists.
a. An Excel file provided by the key author which contains a representation of the character states at each decision point and some optional strings representing the location of multi-media files illustrating the state. At terminal nodes the author will provide information that represents either just a Taxon name and perhaps its Taxonomic rank, or more generally, represents data for a query into an accompanying (or web-accessible) database.
b. An optional database that contains descriptions or other information about the result of keying out a taxon or group of taxa. For example, if the key is to genera or species in a particular family, the database might hold descriptive data sufficient to make up taxon descriptive pages. The database is optional because the key author might be content simply to produce a name as the result of traversing the key.
III. Key tree nodes.
IV. Node structure.
V. Root node
VI. Property lists
VI.1. Property lists on interior nodes
In this document we limit ourselves to the simplest, but most common usage of these attribute-value pairs in the case where the author desires to have renderers produce a multi-media key. In that case interior nodes will typically have a single property, whose attributeNameString is either the word 'image' 'audio' or 'video' and whose <attributeValueString> is a representation of a file name at which the rendering application can locate the media files. It is best that this be somewhat "local" and independent of the exact location on her own computer that the author has stored the media files. For example: attribute=image value=images/thumb/mechanitis.jpg or attribute=video value=video/hiRes/flight1.mpg
VI.2. Property lists on terminal nodes
Terminal, or 'leaf' nodes are nodes with no children. They represent the outcome of a decision made by following a particular path through the tree. Typically, then, they determine a single taxon or group of taxa. Often this group can be described by the result of a query to a database, or it might be as simple as just a taxon name. More importantly, However, we do not actually have to distinguish those two cases: that is the job of the key rendering application, which must have available to it some knowledge of what is intended to happen at leaf nodes. So the simplest property list at a leaf node takes the form attribute=<dbFieldName> value=<dbFieldValue> For example: attribute=Family value=Solanaceae A clever renderer (*) could actually construct a query to the author's database of the form "Display the entry or entries" with Family=Solanaceae. Further, the renderer could be quite sophisticated about what is meant by "Display the entry". For example it could produce a beautiful taxon page, collection of taxon pages, or it could produce XML to be passed to a software program that is invoking the key in some fashion other than by human interaction. Alternatively, a render's behavior could be quite simple, and ignore any database altogether and just indicate that the user has determined that they have keyed out to Family=Solanaceae. As a general principle, the author should make these terminal properties be as "generic" as possible and leave to the rendering application exactly how to deal with it. However, if a database is associated with the key, even conceptually, it is good practice to have something that would provide a simple database query. But it's bad practice to be overly explicit. For example, this is a legal property: attribute=FileMakerQuery value=FMPJS?-db=efg%5fstreams.fp5&-layid=5&-format=formvwcss.htm&-max=1&-token.0=25&-mode=browse&-op=bw&GENUS=Musculium&-lop=and&-find and a rendering application could quite easily be made to deal with it correctly, but it would not survive a change of the database structure, much less of the database software itself. If there are sub-keys for the current key, the author can link to them by following similar principles as above but by using the key word "url" for the attribute name. For example: attribute=url value=subKeyName If the author has static html pages as their species page, they could use that for the value property of property above, but that will not survive changes to the url where the static pages are located.
VI.3 Structured propery lists.
Sometimes the author desires that several properties by considered in aggregate (or even have more complex relationships than simple aggregation). Excel comments are pure unstructured text, but if truth be told, we turn them into XML which has substantial ability to structure them. Therefore we have to give an author a way to guide key renderers about this structure. The simplest case is illustrated here. For more complex cases, see the PLD Tree Reference Manual. attribute=efg:Structure#TaxonGroup value=efg:start attribute=Species value=Mechanitis polymnia attribute=Species value=Mechanitis lysimnia attribute=efg:Structure#TaxonGroup value=efg:end In this example, the optional indentation is ignored---it is just an aid to readability. The above example might be used when a key can not resolve beyond the two species mentioned. The strings efg:Structure, efg:start, and efg:end are reserved (see the PLD Tree Reference Manual). However, they do not place explicit requirements on a key rendering application. Rather the key author must negotiation with the author of the key rendering application what is intended by aggregating the two properties in this way. The tag 'TaxonGroup' following the '#' is chosen by the author (**) and typically this tag will be used to help the tree renderer decide which among possibly several different structures is intended by the key author. Again, this would be part of the specification of a key rendering application negotiated between the key author and the author of the rendering application.