Difference between revisions of "Template:Key Start/doc"

From Biowikifarm Metawiki
Jump to: navigation, search
(Lead parameters)
 
(20 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{Documentation/subpage}}
 
{{Documentation/subpage}}
 +
'''Current version: 3.4''' This set of templates enables authors to create single-access identification keys (also known as dichotomous or polytomous keys) like they are used in biology, in a manner that is well readable, printable, but also re-usable by other software.
 +
 +
NEWS:
 +
* new: The Key Start infobox on top is collapsible, with new Key Start parameter: "collapsed=1" it can be set to be initially collapsed. This should make the Key Start No Heading template redundant!
 +
* Keys work better in combinations with floating images due to adding "clear:both" at the top.
 +
* category field in Key Start supported
 +
* new combination in Lead to differentiate between the result target and the result display text: the old ''resultlink'' is no longer supported, and the new option is to use "result=" plus "result text=". (pagename+display-text).
 +
* ''resulttext'' is deprecated, ''result text'' preferred.
 +
* ''resultqualifier'' is deprecated, ''result qualifier'' preferred.
 +
** '''Question: probably need to support "result qualifier" with blank?'''
 +
* If result text is supplied, result may be unformatted and contain a "#(id-code)" at the end (for internal links!)
 +
* new: parent key (page name if formatting stripped), or parent key + parent key text (pagename+display-text) combinations in Key Start.
 +
* where parent key is missing, an internal category is created: <nowiki>[[Category:Management - Keys without Parent Key|en]] / [[Category:Intern - Übergeordneter Schlüssel fehlt|de]]</nowiki>
 +
* "common names" and "commonnames" are both supported (in Lead and Key start)
 +
* The always-visible images j/k below statement are tested and documented
 +
* A new separate template [[Template:Lead_Link]] enables authors to add hyperlinked cross-references to couplets inside the statement text (in addition to the normal next-couplet links of the key itself).
  
 
=== Highlights===
 
=== Highlights===
  
* Uses standard mediawiki template syntax. The basic structure is a wrapper for entire key, and a sequence of Lead or LeadQuestion templates. Each Lead template contains three unnamed parameters: (1) The lead number, optionally with a backlink; (2) the lead statement, and (3) the result as lead number or a taxon name. In the case of taxon names, it is possible to replace the unnamed 3rd parameter with an explicit parameter called "taxon=". In addition, the named parameters "image", "images" (a synonym) and "description" allow additional information to be given. In edit view, keys looks like:
+
* The identification key is displayed using standard mediawiki "template syntax", not a purpose-built software extension. This means it is stable over a long time, and will not stop working when the mediawiki software is upgraded to new version. It is therefore suitable as an archive format over a long period.
 +
* It uses a layout well known from printed works and is printable itself. The implementation of leader-dots leading up to the right-hand lead pointers makes it usable on different screen resolutions as well as on paper.
 +
* The key is a data structure that can be read by software. This enables the use of specialized players that allow more interactive usage, such as displaying only one couplet at a time. Furthermore, editors that simplify creating a key are planned.
 +
* In addition to the standard structure of lead-number, lead-statement, lead-pointer-or-result, the author can supply supporting text and image information.
 +
* Text information can be structured into synonyms, (additional) description, occurrence and remarks. It is possible to supply further fields here. The purpose of the description field is to provide space for supplementary descriptive information, that did not occur in the statements, but is relevant in the case of incomplete specimens or as check characters.
 +
* A wrappable image gallery:
 +
** This supports up to 6 images, each with a label (letter or number) and caption (free form text) below it. The images will automatically wrap into the available space, using one, or multiple rows depending on the width of the screen. As a drawback for long caption text requiring more than 2 line, this requires specifying the number of "captionlines"; otherwise scrollbars will appear.
 +
** The size of the images can be specified for all images together (secondary images width), or for each image individually. Normally, images will be automatically resized to this size. This creates undesirably fuzzy images if the image is originally smaller than the target size; in this case one has to add the size of the image to each image that is smaller.
 +
** The images below the key offer an "imagesfooter" parameter, which puts a a note below all images together. This is useful of joint captions or attribution sources for all images together.
 +
* Minor features:
 +
** The right-hand-side lead numbers are hyperlinked: in a long key you can click on them and jump directly to the right couplet.
 +
** If a key author uses backlinks (example: "12 (4)" to express "couplet/question number 12, coming from couplet/question number 4"), the backlink will also be hyperlinked. However, currently this precludes the use of a single bracket after the lead ("10 a" is ok , "10 a)" currently creates an error, which will hopefully some day be fixed...)
 +
** A key may contain subheadings to simplify orientation (use "<nowiki>{{Lead | subheading = The heading title | 1 a | statement text... }}</nowiki>")
 +
 
 +
==Using the single access key templates==
 +
 
 +
The basic structure is a '''Key Start''' template, containing metadata such as title, description, and author for the entire key, a sequence of '''Lead''' (or '''Lead Question''' plus Lead) templates containing the key itself, and a final '''Key End''' template. The sequence of lead statements can be further structured by adding a '''subheading''' parameter to the first lead in the first couplet of larger key sections to help humans to jump to specific portions of a key.
 +
 
 +
Each '''Lead''' template contains three unnamed parameters: (1) The lead number, optionally with a backlink; (2) the lead statement, and (3) the result as lead number or a taxon name. In the case of taxon names, it is possible to replace the unnamed 3rd parameter with an explicit parameter called "taxon=". In addition, the named parameters "images" and "description" allow additional information to be given. In edit view, keys looks like:
  
 
  <nowiki>{{Key Start| id = Example | title = Example key | description = Only a demo }}</nowiki>
 
  <nowiki>{{Key Start| id = Example | title = Example key | description = Only a demo }}</nowiki>
 
  <nowiki>{{Lead | 1 | Blätter gegenständig    |  2 }}</nowiki>
 
  <nowiki>{{Lead | 1 | Blätter gegenständig    |  2 }}</nowiki>
 
  <nowiki>{{Lead | 1 | Blätter wechselständig  | 18  </nowiki>
 
  <nowiki>{{Lead | 1 | Blätter wechselständig  | 18  </nowiki>
  <nowiki>  |image=[[Image:xyz.jpg|thumb|200px|A caption for the image]]  }}</nowiki>
+
  <nowiki>  | image a =Image:xyz.jpg </nowiki>
  <nowiki> ... any number of leads ...</nowiki>
+
<nowiki>  | caption a=A caption for the first image }}</nowiki>
 +
  <nowiki> ... any number of leads ...</nowiki>
 
  <nowiki>{{Key End}}</nowiki>
 
  <nowiki>{{Key End}}</nowiki>
  
Line 20: Line 55:
 
* '''Taxon or character images with captions and automatic resizing may be added to any lead (whether a taxon lead or not).'''
 
* '''Taxon or character images with captions and automatic resizing may be added to any lead (whether a taxon lead or not).'''
  
=== Usage ===
 
  
The templates [[Template:SingleAccessKey]] and [[Template:Lead]] are to be used in combination. Please switch into edit or view mode using the tab on top of the screen to see the "code" calling the templates.
+
=== Key metadata (creators, audience, status, etc.) ===
  
{{Key Start | id = MainKey | title = Example key in German | description = This key is a demo key only, containing links to the German Wikipedia}}
+
The following parameters are available directly in the '''Key Start''' template. They serve as metadata for the entire key (small text at the end indicates the mapping to [[http://www.keytonature.eu/wiki/Resource_Metadata_Exchange_Agreement Key to Nature metadata fields]] or MRTG fields):
{{Lead | 1 | Blätter [http://de.wikipedia.org/wiki/Phyllotaxis#Grundtypen gegenständig]  |  2 }}
+
* '''id:''' 1-10 characters, no blank. Highly recommended; necessary if multiple keys exist on a single page. <small>(K2N/MRTG: Resource ID)</small>
 +
* '''title:''' The title of the key, presented as a heading above the key <small>(K2N/MRTG: Title)</small>
 +
* '''language:''' The language of the key. By default, a key is assumed to be in the default language of the wiki it is on. Note: Language is presently not shown in the header area, but may be important when indexing and searching keys form multiple sources. <small>(K2N/MRTG: Language)</small>
 +
* '''geoscope:''' geographic scope <small>(K2N/MRTG: Locality (not fully matching, any better?)</small>
 +
* '''audience:''' the intended audience: 12 yr old school children, 6th grade, university students, general public, experts, etc. <small>(K2N/MRTG: Audience)</small>
 +
* '''description:''' optional, full text description, elaborating information not yet captured in title, geoscope, audience etc. <small>(K2N/MRTG: Description)</small>
 +
* '''source:''' published source citation, if key itself was previously published. If key was newly developed, based on multiple publications, these should normally not be cited here. <small>(K2N/MRTG: Published Source)</small>
 +
* '''collaboration limited to:''' a list of names, to which the collaboration shall be limited. Else "collaboration: open" is shown.  <small>(K2N/MRTG:  NOT APPLICABLE?)</small>
 +
* '''status:''' Progress and status, e.g. "incomplete", "finished" <small>(K2N/MRTG: NOT APPLICABLE?)</small>
 +
* '''creators:''' The main creator(s) of a key, i.e. the ones to be cited as primary authors in the title line. <small>(K2N/MRTG: Creators)</small>
 +
* '''initiated by:''' Initiator(s) of a key project, who does not wish to be cited as primary author <small>(K2N/MRTG: Contributors (pro parte))</small>
 +
* '''edited by:''' A list of editors desiring editor-authorship <small>(K2N/MRTG: Contributors (pro parte))</small>
 +
* '''general review by:''' Persons that have acted as reviewers and quality control editors <small>(K2N/MRTG: Reviewer Names (pro parte))</small>
 +
* '''nomreview by:''' Nomenclatural review <small>(K2N/MRTG: Reviewer Names (pro parte)</small>
 +
* '''expert review by:''' Review by a taxonomic expert of the group. <small>(K2N/MRTG: Reviewer Names (pro parte))</small>
 +
* '''parent key:''' page name (displayed as link) of the key for the next higher taxonomic level, from which the present key is reached as result
 +
* '''parent key text:''' display text for the link to the parent key, works only if parent key is supplied
 +
* '''category''': a list of categories, like Flora, Fauna
 +
* '''flags''': special flags added to the key (multiple flags are separated by Blank, not comma). Primarily evaluated by javascript, but other uses are possible. Flags evaluated by [[MediaWiki:JKey.js]]: jkey-nocontrols (OK), jkey-autostart (FAIL nested keys), jkey-simplified (NEEDS TESTING).
 +
 
 +
<div style="font-size:70%">
 +
: TECHNICAL: To map the content to Key to Nature metadata, the following fields should be filled automatically:
 +
:* Type = Identification Tool
 +
:* Host Application = Web Browser
 +
:* Interactivity = Dynamic
 +
:* ID Tool Structure = polytomous
 +
:* Copyright Statement = Copyright reserved by the contributing authors
 +
:* License Statement = licensed under Creative Commons cc-by-sa 3.0
 +
:* License URL = http://creativecommons.org/licenses/by-sa/3.0/
 +
:* Best Quality Availability = online (free)
 +
:* Best Quality URI = (the URL of the current wiki page, if id-field is present, add "#" and the id.
 +
:In addition, if language was not given expressedly, it should default to the wikis language. Problem: it is unclear how to get this for an ingestion tool without making a specific mediawiki API call...
 +
</div>
 +
 
 +
Note: The '''Key End''' template has no parameters. '''It must, however, always be present''' at the end of a key (it closes the table opened by Key Start).
 +
 
 +
=== Lead parameters ===
 +
 
 +
The following parameters are available in the Lead templates and are listed here for reference. To learn creating keys it will generally, however, be easier to pick a suitably similar example key, switch the wiki into edit mode, and look how it is been done there.
 +
* subheading: A heading that can be interspersed into a key; it will be displayed in in front of the couplet (it should always be used in the first lead of a couplet) for which it is designed.
 +
* subheadingstyle: either a set of css definitions, or one of the following symbolic styles: orange, green, bigorange, biggreen, simple.
 +
* 3 unnamed parameters (those not starting with a "fieldname=" construction). These are, in order:
 +
** The couplet and lead number
 +
** The full statement of the lead (or answer to previous Lead question)
 +
** The next couplet number (without a lead-differentiator, i.e. "34", not "34 a")
 +
** Any further unnamed parameter will be reported as an error. Note also, that if the statement contains an equal sign ("="), it cannot be used with an unnamed parameter. In this case, use "2=your statement text | 3=34"
 +
* commonnames (or "common names"): The common name(s) of an organism, in cases where you want to link using the scientific name.
 +
* result: Formatted text, which will - after unformatting - also be used as the link target for the result. Example: "<nowiki>''Aus bus'' var. ''xus''</nowiki>" will display as "''Aus bus'' var. ''xus''" and link to "Aus bus var. xus" (i.e. without the apostrophes).
 +
* resultlink: '''(Avoid to use! - will be turned off in the future!''' Use result plus resulttext instead)specific link (a wiki page name, like "Lamium album") different from the result parameter (which then defines the display text). It is preferable to add additional information in resultqualifier instead using result text.
 +
 
 +
 
 +
Use this option only exceptionally: it is good if the page name and the link shown are identical. to keep "result" the linked page name (placing additional information in resultqualifiers).
 +
* resultqualifier: an additional text appearing after results, but not becoming part of the link. Where the result is given as a common name, this may contain the scientific name, or it may contain the scientific author names. In other cases it may contain stage "(2nd instar)", sex "(♀♀)", or variety "(white form)" information. In many cases, adding brackets "()" will be desirable.
 +
 
 +
Up to 2 (j and k) larger images (default height/width = 400 x 400, preserving aspect ratio) that are always visible betwen the lead statement:
 +
* image j, label j, caption j, image j width, image j height
 +
* image k, label k, caption k, image k width, image k height
 +
 
 +
Up to 5 (a to e) small images may be displayed in a sidebar:
 +
* For the first ("a") the following parameters are available:
 +
** image a: the image name on the wiki, for example: File:YourImageName.jpg
 +
** label a: a letter or number, placed in the lower right corner over the image, allowing the image to be referred to from the main lead text.
 +
** caption a: Longer text describing or explaining the image. For the sidebar images, this text will only be present in a tooltip on mouse-over-wait actions.
 +
** image a width: desired final width in pixel. The default is 80 pixels
 +
** image a height: desired final height in pixel. The default is 80 pixels
 +
Example: <nowiki>| image a = xyz.jpg | label a = xyz | caption a = abc | image a width = 100 </nowiki>
 +
* image b, image c, image d, image e follow the same pattern (label b etc.)
 +
* For all images together:
 +
** primary images width: Default is 80 pixels
 +
** primary images height: Default is 80 pixels, preserving aspect ratio
 +
 
 +
The following information may be displayed below the lead; it will typically be initially invisible and be shown only after clicking on a "more..." function link.
 +
* synonyms: scientific or common names.
 +
* description: free from additional description
 +
* occurrence: geographic or habitat/ecological distribution. The information will be presently simply appended to the description, but this may be changed later on.
 +
* remarks: free text for additional remarks, including historic or current uses by humans, clues to help to memorize characteristics of the organism, etc. The information will be presently simply appended to the description, but this may be changed later on.
 +
* up to 6 (letters "m" to "r") small images. The same parameters as for the sidebar images are available. The caption will be displayed full readable.
 +
* captionlines: due to the way image m to image r can wrap to the available space, the space for all captions together must be fixed. If undesired scrollbars appear within the caption area of some images, set captionlines to a value larger than 2
 +
* imagesfooter: a free from text displayed below all images together.
 +
* extra images width: like primary images width, but for "image m" to "image r", default is 200 px
 +
* extra images height: see above, default is 200 px, preserving aspect ratio
 +
 
 +
=== Usage Examples ===
 +
 
 +
The templates [[Template:Key Start]], [[Template:Lead]], and  [[Template:Key End]] are to be used in combination. Please switch into edit or view mode using the tab on top of the screen to see the "code" calling the templates.
 +
 
 +
{{Key Start | id = MainKey | title = Example key in German | description = This key is a demo key only, containing links to the German Wikipedia | creators = Author of Key | language = de }}
 +
{{Lead | 1 | Blätter [http://de.wikipedia.org/wiki/Phyllotaxis#Grundtypen gegenständig]  |  2
 +
| image m  = File:Ulistnienie.png
 +
| caption m = Gegenständige (a) und wechselständige (b-d) Anordnung
 +
| image m width = 300  | image m height = 120
 +
}}
 
{{Lead | 1 | Blätter [http://de.wikipedia.org/wiki/Phyllotaxis#Grundtypen wechselständig]  |  18}}
 
{{Lead | 1 | Blätter [http://de.wikipedia.org/wiki/Phyllotaxis#Grundtypen wechselständig]  |  18}}
 
{{Lead | 2 | Blätter handförmig gelappt  |  3 }}
 
{{Lead | 2 | Blätter handförmig gelappt  |  3 }}
 
{{Lead | 2 | Blätter nicht gelappt  |  6 }}
 
{{Lead | 2 | Blätter nicht gelappt  |  6 }}
{{Lead | 3 | Blätter mit 3 Lappen. Blüten weiß. Frucht fleischig  | Gemeiner Schneeball - ''Viburnum opulus'' L.  
+
{{Lead | 3 | Blätter mit 3 Lappen. Blüten weiß. Frucht fleischig  
  |images=[[Image:EFG-logo2.jpg|thumb|200px|random picture demonstrating that images and caption are possible inside the key]]
+
  | result      = ''Viburnum opulus'' L.  
   |description=Der Strauch kann Wuchshöhen von 1,5 bis 4 m erreichen. Die gegenständigen, gestielten Laubblätter sind drei- bis fünflappig. Die weißen Blüten stehen in Trugdolden. Die erbsengroße rote Beere enthält einen Samen.
+
| commonnames = Gemeiner Schneeball
 +
| image a  = File:Viburnum_opulus_B.jpg
 +
| caption a = Flowers - just a demo here that images and caption are possible inside the key
 +
| image b   = File:Viburnum 01.JPG
 +
| caption b = Fruits - both images come from wikimedia commons
 +
| description=Der Strauch kann Wuchshöhen von 1,5 bis 4 m erreichen. Die gegenständigen, gestielten Laubblätter sind drei- bis fünflappig. Die weißen Blüten stehen in Trugdolden. Die erbsengroße rote Beere enthält einen Samen.
  
Bestäuber sind inbesondere Fliegen, die ähnlich wie bei den Doldenblütlern auf dem Blütenstand umherlaufen und die Bestäubung vollziehen.}}
+
| remarks = Bestäuber sind inbesondere Fliegen, die ähnlich wie bei den Doldenblütlern auf dem Blütenstand umherlaufen und die Bestäubung vollziehen.}}
 
{{Lead | 3 | Blätter mit 5 Lappen. Blüten nicht weiß. Frucht trocken, geflügelt  |  4 }}
 
{{Lead | 3 | Blätter mit 5 Lappen. Blüten nicht weiß. Frucht trocken, geflügelt  |  4 }}
{{Lead | 4 | Blätter weniger als 10 cm lang  | Feldahorn - ''Acer campestre'' L. }}
+
{{Lead | 4 (3) | Blätter weniger als 10 cm lang
{{Lead | 4 | Blätter mehr 10 cm lang  |  5 }}
+
  | result      = ''Acer campestre'' L.  
 +
| commonnames = Feldahorn
 +
}}
 +
{{Lead | 4 (3) | Blätter mehr 10 cm lang  |  5 }}
 
{{Key End}}
 
{{Key End}}
  
  
{{Key Start | id = Key2 | title = Start of an English Key with backlinks, links to English Wikipedia, and a footnote}}
+
{{Key Start | id = Key2 | title = Start of an English Key with backlinks, links to English Wikipedia, and a footnote | description= the footnote uses the normal wiki method of using  <nowiki><ref>footnote text</ref></nowiki> inside the lead and a <nowiki><small><references/></small></nowiki> command below the key.| language = en }}
 
{{Lead | 1    | Trees, shrubs, or woody climbers > 50 cm high| 2 }}
 
{{Lead | 1    | Trees, shrubs, or woody climbers > 50 cm high| 2 }}
 
{{Lead | 1    | Herbs or small shrubs (< 50 cm high) | 17 }}
 
{{Lead | 1    | Herbs or small shrubs (< 50 cm high) | 17 }}
 
{{Lead | 2 (1)| Leaves [http://en.wikipedia.org/wiki/Phyllotaxis opposite] | 3 }}
 
{{Lead | 2 (1)| Leaves [http://en.wikipedia.org/wiki/Phyllotaxis opposite] | 3 }}
 
{{Lead | 2    | Leaves [http://en.wikipedia.org/wiki/Phyllotaxis alternate] | 4 }}
 
{{Lead | 2    | Leaves [http://en.wikipedia.org/wiki/Phyllotaxis alternate] | 4 }}
{{Lead | 3 (2)| Leaves bad-smelling when crushed. Fruit fleshy, red | ''Sambucus racemosa'' L. }}
+
{{Lead | 3 (2)| Leaves bad-smelling when crushed. Fruit fleshy, red  
{{Lead | 3    | Leaves odourless. Fruit dry, winged  | [http://en.wikipedia.org/wiki/Acer_negundo ''Acer negundo'' L.]}}
+
|result = ''Sambucus racemosa'' L. }}
 +
{{Lead | 3    | Leaves odourless. Fruit dry, winged  
 +
  |result = ''Acer negundo'' L.}}
 
{{Lead | 4 (2)| Leaves lobed | 5 }}
 
{{Lead | 4 (2)| Leaves lobed | 5 }}
 
{{Lead | 4    | Leaves not lobed | 6  
 
{{Lead | 4    | Leaves not lobed | 6  
  |images=[[Image:EFG-logo2.jpg|thumb|50px|(demo)]] }}
+
|images=[[Image:EFG-logo2.jpg|thumb|50px|(demo)]] }}
{{Lead | 5 (4)| Leaves pinnately-veined. Fruit an acorn. Tree  | [http://en.wikipedia.org/wiki/Quercus_robur ''Quercus robur''] L. }}
+
{{Lead | 5 (4)| Leaves pinnately-veined. Fruit an acorn. Tree  
 +
  |result = ''Quercus robur'' L. }}
 
{{Lead | 5    | Leaves palmately-veined. Fruit fleshy. Small shrub <ref>Blackcurrant juice is used for jams, sirup (French ''Cassis'')</ref>  
 
{{Lead | 5    | Leaves palmately-veined. Fruit fleshy. Small shrub <ref>Blackcurrant juice is used for jams, sirup (French ''Cassis'')</ref>  
               | [http://en.wikipedia.org/wiki/Blackcurrant Blackcurrant ''Ribes nigrum'' L.]}}
+
               | result=''Ribes nigrum'' L.
{{Lead | 6 (4)| Leaves compound. Fruit a red mulberry | ''[[Rubus ideus]]'' L. subsp. ''idaeus'' }}
+
              | commonnames = Blackcurrant }}
 +
{{Lead | 6 (4)| Leaves compound. Fruit a red mulberry  
 +
|result =''Rubus idaeus'' L. subsp. ''idaeus'' }}
 
{{Lead | 6    | Leaves entire. Fruit not mulberry-like | 7 }}
 
{{Lead | 6    | Leaves entire. Fruit not mulberry-like | 7 }}
 
{{Key End}}
 
{{Key End}}
Line 63: Line 201:
  
 
{{Key Start | id = KeyQA | title = Example of the start of a key in question-answer-style}}
 
{{Key Start | id = KeyQA | title = Example of the start of a key in question-answer-style}}
{{LeadQuestion | 1    | What is the life form of your plant? }}
+
{{Lead Question | 1    | What is the life form of your plant? }}
 
{{Lead | a  | a tree, shrub, or a woody climber > 50 cm high| 2 }}
 
{{Lead | a  | a tree, shrub, or a woody climber > 50 cm high| 2 }}
{{Lead | b  | a herbs or small shrubs (< 50 cm high) | 17 }}
+
{{Lead | b  | a herbs or small shrubs (< 50 cm high)       | 17 }}
{{LeadQuestion | 2    | Are two leaves on the stem always opposite of each other?
+
{{Lead Question | 2    | Are two leaves on the stem always opposite of each other?
  |images=[[Image:EFG-logo2.jpg|thumb|50px|random picture demo at Question]]}}
+
| image a  = File:Ulistnienie.png
 +
| caption a = opposite (a) and alternate (b-d) leave arrangement<br/>DEMO IMAGE at question
 +
| image a width = 300  | image a height = 120
 +
}}
 
{{Lead | a  | yes  | 3  
 
{{Lead | a  | yes  | 3  
  |images=[[Image:EFG-logo2.jpg|thumb|50px|random picture demo at Answer a)]]}}
+
| image a  = File:Ulistnienie.png
 +
| caption a = DEMO for image at answer instead of question
 +
| image a width = 300  | image a height = 120
 +
}}
 
{{Lead | b  | no, they are alternate | 4  
 
{{Lead | b  | no, they are alternate | 4  
  |images=[[Image:EFG-logo2.jpg|thumb|50px|random picture demo at Answer b)]]}}
+
| image a  = File:Ulistnienie.png
 +
| caption a = DEMO for image at answer instead of question
 +
| image a width = 300  | image a height = 120
 +
}}
 
{{Key End}}
 
{{Key End}}
 
  
 
For testing, also a technical sample of a reticulated key, resulting in a Directed Acyclical Graph (this key is complete, i.e. unlike the other examples it has no dangling leads):
 
For testing, also a technical sample of a reticulated key, resulting in a Directed Acyclical Graph (this key is complete, i.e. unlike the other examples it has no dangling leads):
Line 80: Line 226:
 
{{Lead | 1| statement a| 2 }}
 
{{Lead | 1| statement a| 2 }}
 
{{Lead | 1| statement b| 3 }}
 
{{Lead | 1| statement b| 3 }}
{{Lead | 2| statement a| ''Sambucus racemosa''}}
+
{{Lead | 2| statement a| result=''Sambucus racemosa''}}
 
{{Lead | 2| statement b| 5 }}
 
{{Lead | 2| statement b| 5 }}
 
{{Lead | 3| statement a| 6}}
 
{{Lead | 3| statement a| 6}}
 
{{Lead | 3| statement b| 4}}
 
{{Lead | 3| statement b| 4}}
{{Lead | 4| statement a| ''Acer negundo''}}
+
{{Lead | 4| statement a| result=''Acer negundo''}}
{{Lead | 4| statement b| ''Fraxinus excelsior''}}
+
{{Lead | 4| statement b| result=''Fraxinus excelsior''}}
{{Lead | 5| statement a| ''Rubus fruticosus'' }}
+
{{Lead | 5| statement a| result=''Rubus fruticosus'' }}
{{Lead | 5| statement b| ''Ribes nigrum''}}
+
{{Lead | 5| statement b| result=''Ribes nigrum''}}
 
{{Lead | 6| statement a| 4}}
 
{{Lead | 6| statement a| 4}}
{{Lead | 6| statement b| ''Rubus ideus''}}
+
{{Lead | 6| statement b| result=''Rubus ideus''}}
 
{{Key End}}
 
{{Key End}}
  
 
+
{{Key Start | id = ErrorDemo | title = Error Demo '''(the red errors are intentional here!)'''| description = The templates will report some errors already, e.g. putting text or images into an unnamed 4th or 5th parameter, including putting images or taxon description there without using the named parameter (images= or description=) for this }}
{{Key Start | id = JavierKey | title = This is just a test of complicated data structures for Javier's test }}
+
{{Lead | 1 | opposite  | 2 | This text is in the 4th parameter}}
{{Lead | 1 | Blätter [http://de.wikipedia.org/wiki/Phyllotaxis#Grundtypen gegenständig]  |  2 }}
+
{{Lead | 1 | alternate | 4}}
{{Lead | 1 | Blätter [http://de.wikipedia.org/wiki/Phyllotaxis#Grundtypen wechselständig]  |  4}}
+
{{Lead | 2 | pinnate    | 3 }}
{{Lead | 2 | Blätter handförmig gelappt  |  3 }}
+
{{Lead | 2 | not pinnate| 6 }}
{{Lead | 2 | Blätter nicht gelappt  |  6 }}
+
{{Lead | 3 | Blätter mit 3 Lappen. Blüten weiß. Frucht fleischig  |  Gemeiner Schneeball - ''Viburnum opulus'' L.
+
  |images=[[Image:EFG-logo2.jpg|thumb|200px|random picture demonstrating that images and caption are possible inside the key]] }}
+
{{Lead | 3 | Blätter mit 5 Lappen. Blüten nicht weiß. Frucht trocken, geflügelt  | 4 }}
+
{{Lead | 4 | Blätter weniger als 10 cm lang | Feldahorn - ''Acer campestre'' L. }}
+
{{Lead | 4 | Blätter mehr 10 cm lang  | 5 }}
+
{{Lead | 4 | Blätter mehr 10 cm lang  | 5 }}
+
 
{{Key End}}
 
{{Key End}}
  
  
{{Key Start | id = ErrorDemo | title = ErrorDemo | description = The templates will report some errors already, e.g. putting text or images into an unnamed 4th or 5th parameter, including putting images or taxon description there without using the named parameter (image= or description=) for this }}
+
==Information for developers==
{{Lead | 1 | Blätter gegenständig  |  2 | Accidental content in the 4th parameter is reported}}
+
{{Lead | 1 | Blätter wechselständig  |  4}}
+
{{Lead | 2 | Blätter handförmig gelappt  |  3 }}
+
{{Lead | 2 | Blätter nicht gelappt  |  6 | [[Image:EFG-logo2.jpg|thumb|200px|random picture demonstrating that images and caption are possible inside the key]] }}
+
{{Key End}}
+
  
 +
===Layout===
  
===Introduction for developers===
+
The key is a table with a column for lead numbers, a column for alternative codes and backlinks, a third column which in turn contains another two-column table for statement and result (next lead or final taxon) and a fourth column containing optional right-side images. The use of the embedded statement-plus-result table enables to use the available space in the best manner, allowing each row to determine the optimal distribution between statement text and result text. A long lead statement in one row (with a short number pointer) can overlap with a long taxon name in another row. Each lead is a separate row. Secondary images and text may be present in an additional row below the statement and result, which will initially be hidden through javascript (displaying a "more..." link).
  
The key is a table with a dummy column to enable partial overlap between left and right text in different rows. Overlap is possible only between a long lead statement with a short number pointer, long lead statements with a long taxon name can not overlap. Each lead is a separate row, if images are present they are added in an additional row where required.
+
* Compare a FRIDA [http://dbiodbs.units.it/carso/chiavi_pub30?usr=admin&step=2&altro=128&n=1013 html key] for comparison. One major difference is that FRIDA always places the taxon in a row of its own.
  
 
Javascript programmability: Each row contains an id attribute with "L" + lead number + "row", the lead cell itself an id attribute with "L" + lead number. The table is styled mostly using css classes, with the text span background an exception (to allow parameterization of the background).
 
Javascript programmability: Each row contains an id attribute with "L" + lead number + "row", the lead cell itself an id attribute with "L" + lead number. The table is styled mostly using css classes, with the text span background an exception (to allow parameterization of the background).
  
===TODO===
 
 
* Add the key id to each lead id, to support multiple keys on a wikipage. Work on this was started, but not finished!
 
* Improvements: The key title could be displayed better than as caption. The description text could perhaps be styled differently.
 
 
* A FRIDA [http://dbiodbs.units.it/carso/chiavi_pub30?usr=admin&step=2&altro=128&n=1013 html key] for comparison. One major difference is that FRIDA always places the taxon in a row of its own.
 
  
 
===Known problems===
 
===Known problems===
  
# Leads do not automatically renumber.  
+
# Manual lead renumbering is laborious; this occurs in cases where a new lead must be inserted, or the sequence of leads is considered unsatisfactorily.
#* There is an obvious service solutions for this: The project would have to program a "bot" program, the works through all keys that have a category like "Please renumber" set, renumbering the key in an optimal way, and then deleting (or commenting out) the category.
+
#* Suggestion: do not renumber leads while working on the key. Insert new leads with "High" numbers, such as 100, 101 or even 1000, 1001. Only when the key is completed, carefully renumber all leads.
 +
#* A service-oriented solution for this: The project would have to program a "bot" program, the works through all keys that have a category like "Please renumber" set, renumbering the key in an optimal way, and then deleting (or commenting out) the category.
  
  
=== Dependencies ===
+
=== Technical Dependencies ===
  
* Styles in [[MediaWiki:Common.css]], one of which refers to a background image which must be available, and it needs the StringFunctions extension installed.
+
* Styles in [[MediaWiki:Common.css]]. One these styles refers to a background image for the leader dots, which must be available directly on the server
* The internal link target highlighting depends on code in [[MediaWiki:Common.js]]
+
* The internal link target highlighting and the hiding of secondary text and images ("more...") depends on code in [[MediaWiki:Common.js]]
* The associated templates are: [[Template:Key End]], [[Template:Lead]], and [[Template:LeadQuestion]]
+
* The primary templates usable by the identification key author are: [[Template:Key Start]], [[Template:Key End]], [[Template:Lead]], and optionally [[Template:Lead Question]].
* Documentation templates at: [[Template:Key Start/doc]], [[Template:Key End/doc]], [[Template:Lead/doc]]
+
* Many more generic or specific helper-templates are needed, see [[:Category: Single-access key templates]] for a list.
* Secondary tool templates are [[Template:Trim]], [[Template:Documentation]], [[Template:Documentation/subpage]],  [[Template:Documentation/docname]],  [[Template:Documentation/preload]].
+
  
* to function it requires the following active extensions: parser functions (standard on Wikipedia), string functions (not active on Wikipedia, but considered), and variables (not even considered). The use of variables is limited to some functionality which allows deleting it from the Template code if the function is not available. It primarily allows having multiple keys on a single wiki page, with correct linking.
+
* The MediaWiki software must have the following extensions activated: Parser functions (standard on Wikipedia), string functions (not active on Wikipedia, but considered), and variables (not even considered). The use of variables is limited to some functionality which allows deleting it from the Template code if the function is not available. It primarily allows having multiple keys on a single wiki page, with correct linking.
  
<!--
+
<noinclude>[[Category:Single-access key templates]]</noinclude>
=== See also ===
+
-->
+
<includeonly>
+
<!-- add template categories here -->
+
</includeonly>
+

Latest revision as of 11:57, 22 June 2010

This is a documentation subpage for Template:Key Start (see that page for the template itself).
It contains usage information, categories and other content that is not part of the original template page.

Current version: 3.4 This set of templates enables authors to create single-access identification keys (also known as dichotomous or polytomous keys) like they are used in biology, in a manner that is well readable, printable, but also re-usable by other software.

NEWS:

  • new: The Key Start infobox on top is collapsible, with new Key Start parameter: "collapsed=1" it can be set to be initially collapsed. This should make the Key Start No Heading template redundant!
  • Keys work better in combinations with floating images due to adding "clear:both" at the top.
  • category field in Key Start supported
  • new combination in Lead to differentiate between the result target and the result display text: the old resultlink is no longer supported, and the new option is to use "result=" plus "result text=". (pagename+display-text).
  • resulttext is deprecated, result text preferred.
  • resultqualifier is deprecated, result qualifier preferred.
    • Question: probably need to support "result qualifier" with blank?
  • If result text is supplied, result may be unformatted and contain a "#(id-code)" at the end (for internal links!)
  • new: parent key (page name if formatting stripped), or parent key + parent key text (pagename+display-text) combinations in Key Start.
  • where parent key is missing, an internal category is created: [[Category:Management - Keys without Parent Key|en]] / [[Category:Intern - Übergeordneter Schlüssel fehlt|de]]
  • "common names" and "commonnames" are both supported (in Lead and Key start)
  • The always-visible images j/k below statement are tested and documented
  • A new separate template Template:Lead_Link enables authors to add hyperlinked cross-references to couplets inside the statement text (in addition to the normal next-couplet links of the key itself).

Highlights

  • The identification key is displayed using standard mediawiki "template syntax", not a purpose-built software extension. This means it is stable over a long time, and will not stop working when the mediawiki software is upgraded to new version. It is therefore suitable as an archive format over a long period.
  • It uses a layout well known from printed works and is printable itself. The implementation of leader-dots leading up to the right-hand lead pointers makes it usable on different screen resolutions as well as on paper.
  • The key is a data structure that can be read by software. This enables the use of specialized players that allow more interactive usage, such as displaying only one couplet at a time. Furthermore, editors that simplify creating a key are planned.
  • In addition to the standard structure of lead-number, lead-statement, lead-pointer-or-result, the author can supply supporting text and image information.
  • Text information can be structured into synonyms, (additional) description, occurrence and remarks. It is possible to supply further fields here. The purpose of the description field is to provide space for supplementary descriptive information, that did not occur in the statements, but is relevant in the case of incomplete specimens or as check characters.
  • A wrappable image gallery:
    • This supports up to 6 images, each with a label (letter or number) and caption (free form text) below it. The images will automatically wrap into the available space, using one, or multiple rows depending on the width of the screen. As a drawback for long caption text requiring more than 2 line, this requires specifying the number of "captionlines"; otherwise scrollbars will appear.
    • The size of the images can be specified for all images together (secondary images width), or for each image individually. Normally, images will be automatically resized to this size. This creates undesirably fuzzy images if the image is originally smaller than the target size; in this case one has to add the size of the image to each image that is smaller.
    • The images below the key offer an "imagesfooter" parameter, which puts a a note below all images together. This is useful of joint captions or attribution sources for all images together.
  • Minor features:
    • The right-hand-side lead numbers are hyperlinked: in a long key you can click on them and jump directly to the right couplet.
    • If a key author uses backlinks (example: "12 (4)" to express "couplet/question number 12, coming from couplet/question number 4"), the backlink will also be hyperlinked. However, currently this precludes the use of a single bracket after the lead ("10 a" is ok , "10 a)" currently creates an error, which will hopefully some day be fixed...)
    • A key may contain subheadings to simplify orientation (use "{{Lead | subheading = The heading title | 1 a | statement text... }}")

Using the single access key templates

The basic structure is a Key Start template, containing metadata such as title, description, and author for the entire key, a sequence of Lead (or Lead Question plus Lead) templates containing the key itself, and a final Key End template. The sequence of lead statements can be further structured by adding a subheading parameter to the first lead in the first couplet of larger key sections to help humans to jump to specific portions of a key.

Each Lead template contains three unnamed parameters: (1) The lead number, optionally with a backlink; (2) the lead statement, and (3) the result as lead number or a taxon name. In the case of taxon names, it is possible to replace the unnamed 3rd parameter with an explicit parameter called "taxon=". In addition, the named parameters "images" and "description" allow additional information to be given. In edit view, keys looks like:

{{Key Start| id = Example | title = Example key | description = Only a demo }}
{{Lead | 1 | Blätter gegenständig    |  2 }}
{{Lead | 1 | Blätter wechselständig  | 18   
  | image a =Image:xyz.jpg 
  | caption a=A caption for the first image }}
 ... any number of leads ...
{{Key End}}
(Switch this documentation page into edit view to see the text behind the rendered examples on this page.)
  • Users can duplicate any existing key and modify, translate, or shorten it, with requiring an expert or administrator to allow it to them.
  • It is possible to rearrange the key or add new couplets or leads with new taxa.
    • In both cases, renumbering the leads is a problem, but while building a key up, non-consecutive lead numbers can be an interim solution.
  • Both lead statements and taxon links can contain links to internal Wiki pages or external web pages, defining or explaining characters, states, or taxa.
  • Taxon or character images with captions and automatic resizing may be added to any lead (whether a taxon lead or not).


Key metadata (creators, audience, status, etc.)

The following parameters are available directly in the Key Start template. They serve as metadata for the entire key (small text at the end indicates the mapping to [Key to Nature metadata fields] or MRTG fields):

  • id: 1-10 characters, no blank. Highly recommended; necessary if multiple keys exist on a single page. (K2N/MRTG: Resource ID)
  • title: The title of the key, presented as a heading above the key (K2N/MRTG: Title)
  • language: The language of the key. By default, a key is assumed to be in the default language of the wiki it is on. Note: Language is presently not shown in the header area, but may be important when indexing and searching keys form multiple sources. (K2N/MRTG: Language)
  • geoscope: geographic scope (K2N/MRTG: Locality (not fully matching, any better?)
  • audience: the intended audience: 12 yr old school children, 6th grade, university students, general public, experts, etc. (K2N/MRTG: Audience)
  • description: optional, full text description, elaborating information not yet captured in title, geoscope, audience etc. (K2N/MRTG: Description)
  • source: published source citation, if key itself was previously published. If key was newly developed, based on multiple publications, these should normally not be cited here. (K2N/MRTG: Published Source)
  • collaboration limited to: a list of names, to which the collaboration shall be limited. Else "collaboration: open" is shown. (K2N/MRTG: NOT APPLICABLE?)
  • status: Progress and status, e.g. "incomplete", "finished" (K2N/MRTG: NOT APPLICABLE?)
  • creators: The main creator(s) of a key, i.e. the ones to be cited as primary authors in the title line. (K2N/MRTG: Creators)
  • initiated by: Initiator(s) of a key project, who does not wish to be cited as primary author (K2N/MRTG: Contributors (pro parte))
  • edited by: A list of editors desiring editor-authorship (K2N/MRTG: Contributors (pro parte))
  • general review by: Persons that have acted as reviewers and quality control editors (K2N/MRTG: Reviewer Names (pro parte))
  • nomreview by: Nomenclatural review (K2N/MRTG: Reviewer Names (pro parte)
  • expert review by: Review by a taxonomic expert of the group. (K2N/MRTG: Reviewer Names (pro parte))
  • parent key: page name (displayed as link) of the key for the next higher taxonomic level, from which the present key is reached as result
  • parent key text: display text for the link to the parent key, works only if parent key is supplied
  • category: a list of categories, like Flora, Fauna
  • flags: special flags added to the key (multiple flags are separated by Blank, not comma). Primarily evaluated by javascript, but other uses are possible. Flags evaluated by MediaWiki:JKey.js: jkey-nocontrols (OK), jkey-autostart (FAIL nested keys), jkey-simplified (NEEDS TESTING).
TECHNICAL: To map the content to Key to Nature metadata, the following fields should be filled automatically:
  • Type = Identification Tool
  • Host Application = Web Browser
  • Interactivity = Dynamic
  • ID Tool Structure = polytomous
  • Copyright Statement = Copyright reserved by the contributing authors
  • License Statement = licensed under Creative Commons cc-by-sa 3.0
  • License URL = http://creativecommons.org/licenses/by-sa/3.0/
  • Best Quality Availability = online (free)
  • Best Quality URI = (the URL of the current wiki page, if id-field is present, add "#" and the id.
In addition, if language was not given expressedly, it should default to the wikis language. Problem: it is unclear how to get this for an ingestion tool without making a specific mediawiki API call...

Note: The Key End template has no parameters. It must, however, always be present at the end of a key (it closes the table opened by Key Start).

Lead parameters

The following parameters are available in the Lead templates and are listed here for reference. To learn creating keys it will generally, however, be easier to pick a suitably similar example key, switch the wiki into edit mode, and look how it is been done there.

  • subheading: A heading that can be interspersed into a key; it will be displayed in in front of the couplet (it should always be used in the first lead of a couplet) for which it is designed.
  • subheadingstyle: either a set of css definitions, or one of the following symbolic styles: orange, green, bigorange, biggreen, simple.
  • 3 unnamed parameters (those not starting with a "fieldname=" construction). These are, in order:
    • The couplet and lead number
    • The full statement of the lead (or answer to previous Lead question)
    • The next couplet number (without a lead-differentiator, i.e. "34", not "34 a")
    • Any further unnamed parameter will be reported as an error. Note also, that if the statement contains an equal sign ("="), it cannot be used with an unnamed parameter. In this case, use "2=your statement text | 3=34"
  • commonnames (or "common names"): The common name(s) of an organism, in cases where you want to link using the scientific name.
  • result: Formatted text, which will - after unformatting - also be used as the link target for the result. Example: "''Aus bus'' var. ''xus''" will display as "Aus bus var. xus" and link to "Aus bus var. xus" (i.e. without the apostrophes).
  • resultlink: (Avoid to use! - will be turned off in the future! Use result plus resulttext instead)specific link (a wiki page name, like "Lamium album") different from the result parameter (which then defines the display text). It is preferable to add additional information in resultqualifier instead using result text.


Use this option only exceptionally: it is good if the page name and the link shown are identical. to keep "result" the linked page name (placing additional information in resultqualifiers).

  • resultqualifier: an additional text appearing after results, but not becoming part of the link. Where the result is given as a common name, this may contain the scientific name, or it may contain the scientific author names. In other cases it may contain stage "(2nd instar)", sex "(♀♀)", or variety "(white form)" information. In many cases, adding brackets "()" will be desirable.

Up to 2 (j and k) larger images (default height/width = 400 x 400, preserving aspect ratio) that are always visible betwen the lead statement:

  • image j, label j, caption j, image j width, image j height
  • image k, label k, caption k, image k width, image k height

Up to 5 (a to e) small images may be displayed in a sidebar:

  • For the first ("a") the following parameters are available:
    • image a: the image name on the wiki, for example: File:YourImageName.jpg
    • label a: a letter or number, placed in the lower right corner over the image, allowing the image to be referred to from the main lead text.
    • caption a: Longer text describing or explaining the image. For the sidebar images, this text will only be present in a tooltip on mouse-over-wait actions.
    • image a width: desired final width in pixel. The default is 80 pixels
    • image a height: desired final height in pixel. The default is 80 pixels

Example: | image a = xyz.jpg | label a = xyz | caption a = abc | image a width = 100

  • image b, image c, image d, image e follow the same pattern (label b etc.)
  • For all images together:
    • primary images width: Default is 80 pixels
    • primary images height: Default is 80 pixels, preserving aspect ratio

The following information may be displayed below the lead; it will typically be initially invisible and be shown only after clicking on a "more..." function link.

  • synonyms: scientific or common names.
  • description: free from additional description
  • occurrence: geographic or habitat/ecological distribution. The information will be presently simply appended to the description, but this may be changed later on.
  • remarks: free text for additional remarks, including historic or current uses by humans, clues to help to memorize characteristics of the organism, etc. The information will be presently simply appended to the description, but this may be changed later on.
  • up to 6 (letters "m" to "r") small images. The same parameters as for the sidebar images are available. The caption will be displayed full readable.
  • captionlines: due to the way image m to image r can wrap to the available space, the space for all captions together must be fixed. If undesired scrollbars appear within the caption area of some images, set captionlines to a value larger than 2
  • imagesfooter: a free from text displayed below all images together.
  • extra images width: like primary images width, but for "image m" to "image r", default is 200 px
  • extra images height: see above, default is 200 px, preserving aspect ratio

Usage Examples

The templates Template:Key Start, Template:Lead, and Template:Key End are to be used in combination. Please switch into edit or view mode using the tab on top of the screen to see the "code" calling the templates.

Example key in German — Author of Key
This key is a demo key only, containing links to the German Wikipedia
(Geographic scope not specified) — Collaboration: open — (Status not specified) — Edited by: (not specified)
1
1
Blätter wechselständig   ► 18
2
Blätter handförmig gelappt   ► 3
2
Blätter nicht gelappt   ► 6
3
Flowers - just a demo here that images and caption are possible inside the key
Fruits - both images come from wikimedia commons
3
Blätter mit 5 Lappen. Blüten nicht weiß. Frucht trocken, geflügelt   ► 4
4 (3)
Blätter weniger als 10 cm lang    Feldahorn   Acer campestre L.
4 (3)
Blätter mehr 10 cm lang   ► 5


Start of an English Key with backlinks, links to English Wikipedia, and a footnote
the footnote uses the normal wiki method of using <ref>footnote text</ref> inside the lead and a <small><references/></small> command below the key.
(Geographic scope not specified) — Collaboration: open — (Status not specified) — Edited by: (not specified)
1
Trees, shrubs, or woody climbers > 50 cm high   ► 2
1
Herbs or small shrubs (< 50 cm high)   ► 17
2 (1)
Leaves opposite   ► 3
2
Leaves alternate   ► 4
3 (2)
Leaves bad-smelling when crushed. Fruit fleshy, red   Sambucus racemosa L.
3
Leaves odourless. Fruit dry, winged   Acer negundo L.
4 (2)
Leaves lobed   ► 5
4
Leaves not lobed   ► 6
Error: You may have an erroneous 4th unnamed parameter (vertical bar without a field name), or you may use "commonname/common name/remark/results/synonym/image/images" instead of "common names/remarks/result/synonyms/image a" etc. The content is:
(demo)
. To add descriptions use |description=Your text|; to add one or several synonyms use |synonmys=Synonym 1; Synonym 2|; to add images use |image 1a=Image:YourImage.jpg |caption 1a=Your Caption (images a to e are in the sidebar, j following below lead text, with j/k always visible and, images m to r in the "more"-information area below the lead).
5 (4)
Leaves pinnately-veined. Fruit an acorn. Tree   Quercus robur L.
5
Leaves palmately-veined. Fruit fleshy. Small shrub [1]    Blackcurrant   Ribes nigrum L.
6 (4)
Leaves compound. Fruit a red mulberry   Rubus idaeus L. subsp. idaeus
6
Leaves entire. Fruit not mulberry-like   ► 7

  1. Blackcurrant juice is used for jams, sirup (French Cassis)


Single access keys created with these templates may be strictly dichotomous (two alternatives, as above) or they may be polytomous (some couplets having more than 2 alternatives, not shown). Furthermore, it is possible to design keys in statement-style (as above) or in question-answer-style as follows:

Example of the start of a key in question-answer-style
1
What is the life form of your plant?  
a
a tree, shrub, or a woody climber > 50 cm high   ► 2
b
a herbs or small shrubs (< 50 cm high)   ► 17
2
Are two leaves on the stem always opposite of each other?  
a
yes   ► 3
DEMO for image at answer instead of question
b
no, they are alternate   ► 4
DEMO for image at answer instead of question

For testing, also a technical sample of a reticulated key, resulting in a Directed Acyclical Graph (this key is complete, i.e. unlike the other examples it has no dangling leads):

Techical example of reticulated key (lead 4 has two parents: 3 and 6)
1
statement a   ► 2
1
statement b   ► 3
2
statement a   Sambucus racemosa
2
statement b   ► 5
3
statement a   ► 6
3
statement b   ► 4
4
statement a   Acer negundo
4
statement b   Fraxinus excelsior
5
statement a   Rubus fruticosus
5
statement b   Ribes nigrum
6
statement a   ► 4
6
statement b   Rubus ideus
Error Demo (the red errors are intentional here!)
The templates will report some errors already, e.g. putting text or images into an unnamed 4th or 5th parameter, including putting images or taxon description there without using the named parameter (images= or description=) for this
(Geographic scope not specified) — Collaboration: open — (Status not specified) — Edited by: (not specified)
1
opposite   ► 2
Error: You may have an erroneous 4th unnamed parameter (vertical bar without a field name), or you may use "commonname/common name/remark/results/synonym/image/images" instead of "common names/remarks/result/synonyms/image a" etc. The content is: This text is in the 4th parameter . To add descriptions use |description=Your text|; to add one or several synonyms use |synonmys=Synonym 1; Synonym 2|; to add images use |image 1a=Image:YourImage.jpg |caption 1a=Your Caption (images a to e are in the sidebar, j following below lead text, with j/k always visible and, images m to r in the "more"-information area below the lead).
1
alternate   ► 4
2
pinnate   ► 3
2
not pinnate   ► 6


Information for developers

Layout

The key is a table with a column for lead numbers, a column for alternative codes and backlinks, a third column which in turn contains another two-column table for statement and result (next lead or final taxon) and a fourth column containing optional right-side images. The use of the embedded statement-plus-result table enables to use the available space in the best manner, allowing each row to determine the optimal distribution between statement text and result text. A long lead statement in one row (with a short number pointer) can overlap with a long taxon name in another row. Each lead is a separate row. Secondary images and text may be present in an additional row below the statement and result, which will initially be hidden through javascript (displaying a "more..." link).

  • Compare a FRIDA html key for comparison. One major difference is that FRIDA always places the taxon in a row of its own.

Javascript programmability: Each row contains an id attribute with "L" + lead number + "row", the lead cell itself an id attribute with "L" + lead number. The table is styled mostly using css classes, with the text span background an exception (to allow parameterization of the background).


Known problems

  1. Manual lead renumbering is laborious; this occurs in cases where a new lead must be inserted, or the sequence of leads is considered unsatisfactorily.
    • Suggestion: do not renumber leads while working on the key. Insert new leads with "High" numbers, such as 100, 101 or even 1000, 1001. Only when the key is completed, carefully renumber all leads.
    • A service-oriented solution for this: The project would have to program a "bot" program, the works through all keys that have a category like "Please renumber" set, renumbering the key in an optimal way, and then deleting (or commenting out) the category.


Technical Dependencies

  • The MediaWiki software must have the following extensions activated: Parser functions (standard on Wikipedia), string functions (not active on Wikipedia, but considered), and variables (not even considered). The use of variables is limited to some functionality which allows deleting it from the Template code if the function is not available. It primarily allows having multiple keys on a single wiki page, with correct linking.