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

Revision as of 22:31, 1 December 2008

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:

{{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=[[Image:xyz.jpg|thumb|200px|A caption for the 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).

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.

Example key in German
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
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. 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: random picture demonstrating that images and caption are possible inside the key . 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). 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		Blätter weniger als 10 cm lang    ► Feldahorn - Acer campestre L.
4		Blätter mehr 10 cm lang    ► 5

Start of an English Key with backlinks, links to English Wikipedia, and a footnote

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   [[#LKey2_Acer negundo L.| ► 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   [[#LKey2_Quercus robur L.| ► Quercus robur L.]]
5		Leaves palmately-veined. Fruit fleshy. Small shrub [1]   [[#LKey2_Blackcurrant Ribes nigrum L.| ► Blackcurrant Ribes nigrum L.]]
6	(4)	Leaves compound. Fruit a red mulberry   [[#LKey2_Rubus ideus L. subsp. idaeus| ► Rubus ideus 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?
		random picture demo at Question
a		yes    ► 3 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: random picture demo at Answer a) . 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).
b		no, they are alternate    ► 4 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: random picture demo at Answer b) . 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).

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

This is just a test of complicated data structures for Javier's test

1		Blätter gegenständig    ► 2
1		Blätter wechselständig    ► 4
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. 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: random picture demonstrating that images and caption are possible inside the key . 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).
3		Blätter mit 5 Lappen. Blüten nicht weiß. Frucht trocken, geflügelt    ► 4
4		Blätter weniger als 10 cm lang    ► Feldahorn - Acer campestre L.
4		Blätter mehr 10 cm lang    ► 5
4		Blätter mehr 10 cm lang    ► 5

ErrorDemo
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 (Geographic scope not specified) — Collaboration: open — (Status not specified) — Edited by: (not specified)

1		Blätter gegenständig    ► 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: Accidental content in the 4th parameter is reported . 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		Blätter wechselständig    ► 4
2		Blätter handförmig gelappt    ► 3
2		Blätter nicht gelappt    ► 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: random picture demonstrating that images and caption are possible inside the key . 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).

Introduction for developers

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.

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 html key for comparison. One major difference is that FRIDA always places the taxon in a row of its own.

Known problems

1. A plain three column layout is less than satisfactory; the occasional wide taxon names force the whole last column to be very wide.
   • To some extent, this is already worked around by providing a four-column layout with alternating colspan (33% of table width is assigned to statement, if no taxon is present, or to taxon, if that is present. However, this still means that the statement may be presented shorter than necessary.
2. Clicking on the hyperlinks usually has no effect if the screen already contains the target lead.
   • Proposed solution: some javascript additions. Note: JS can not be called directly from within the wiki text for security reasons, or any user could reprogram the wiki into a dangerous tool.
3. Leads do not automatically renumber.
   • 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.
4. There are no lead dots running from the statement to the number.
   • Attempting to fix this with <span style="float:right"> . . . .</span> did not work well!
   • Can this be fixed with a repeated background image and non-transparent text? Could be worth testing!

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.
• The target highlighting depends on code in MediaWiki:Common.js
• The associated templates are: Template:Lead, and Template:LeadQuestion
• Documentation templates at: Template:SingleAccessKey/doc, Template:Lead/doc
• 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.