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

Latest revision as of 11:57, 22 June 2010

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).

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		Blätter gegenständig    ► 2 Gegenständige (a) und wechselständige (b-d) Anordnung
1		Blätter wechselständig    ► 18
2		Blätter handförmig gelappt    ► 3
2		Blätter nicht gelappt    ► 6
3		Blätter mit 3 Lappen. Blüten weiß. Frucht fleischig     Gemeiner Schneeball   Viburnum opulus L. 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.
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

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
b		no, they are alternate    ► 4

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):

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

• 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 and the hiding of secondary text and images ("more...") depends on code in MediaWiki:Common.js
• The primary templates usable by the identification key author are: Template:Key Start, Template:Key End, Template:Lead, and optionally Template:Lead Question.
• Many more generic or specific helper-templates are needed, see Category: Single-access key templates for a list.

• 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.