====== Keyboard Plugin ======



===== Description =====

The keyboard plugin provides a combined syntax and action plugin in order to markup text as keyboard keys, similar to (and making use of) the existing (X)HTML tag ''<kbd>...</kbd>''. A quick button for the markup is automatically inserted into the toolbar of the edit form.

In case you come across any bugs in this plugin, don't hesitate to [[http://flyspray.foosel.net/index.php?tasks=all&project=4|report them]].

The Darcs repository of the plugin can be found [[http://devel.foosel.org/darcsweb/darcsweb.cgi?r=dokuwiki/keyboard;a=summary|here]].

===== Updates =====

**Last updated:** 2008/05/04

  * 2008/05/04:
    * [[bug>25]] fixed, toolbar button works again. You will have to purge your cached javascript after upgrading by opening ''http://your.domain.com/path/to/dokuwiki/lib/exe/js.php?edit=1&write=1&purge=1'' in your browser of choice.
  * 2007/07/17:
    * Fixed a small bug in the german language file (swapped Pageup/Pagedown translations, thanks go to Werner Mayer for the tip-off).
  * 2007/04/11:
    * Fixed the stylesheetname (''styles.css'' => ''style.css'', thanks to John Friar for the heads-up)
  * 2007/04/05:
    * Added additional small action plugin to insert a button into the toolbar of the edit form <del>([[http://wiki.splitbrain.org/wiki:develonly|Development version only]])</del>.
  * 2007/04/03:
    * Fixed typo in english language file.
  * 2007/03/30:
    * Bugfix: [[bug>12]] 
  * 2005/10/10:
    * Small bugfix (''substitution'' => ''substition'')
  * 2005/10/02:
    * Keycombination support

===== Acknowledgements =====

Special thanks to Christopher Arndt for suggestions and enhancements.

===== Syntax =====

Enclose the name of a key, or a combination of keys, separated by a dash (**''-''**), in a //key// tag, like this:

  <key>Key</key> or <key>C-x</key>

    * The text inside the **''key''** tag is split at the occurrences of **''-''** (dash).
    * Each part is //trimmed// (surrounding whitespace removed) and known shortcuts or key names are //substituted//. E.g. **''C''** becomes **''Ctrl''**, **''Left''** becomes **''%%&larr;%%''** etc.
    * The substitutions are //language specific//. So, e.g. in German, **''C''** becomes **''Strg''** and **''Del''** becomes **''Entf''**. Only English and German are supported at the moment. Feel free to write additional language files and send them in for inclusion.
    * If no substitution was found, the first letter is //capitalized// and special HTML chars are replaced with entities.
    * The substitution table only has key aliases that begin with a capital letter. So lower letters will not be substituted, only capitalized and, for example, **''C-c''** becomes **''Ctrl-C''**
    * If you want to express the dash (**''-''**) key, use **''Minus''**.
    * If you don't want any trimming, alias or language substitution, or capitalization, enclose your key name in //single// quotes.

**Examples:**

  * <key>C-A-del</key> to reboot. (''%%<key>C-A-del</key>%%'')
  * <key>C - c</key> to copy text to the clipboard. (''%%<key>C - c</key>%%'')
  * <key>C-x</key> to cut text and put it into the clipboard. (''%%<key>C-x</key>%%'')
  * <key>C-v</key> to paste text from the clipboard. (''%%<key>C-v</key>%%'')
  * <key>C-enter</key> to insert a page break. (''%%<key>C-enter</key>%%'')
  * <key>C-S-Right</key> to select from current cursor position to end of a word. (''%%<key>C-S-Right</key>%%'')
  * <key>C-S-Left</key> to select from current cursor position to the beginning of a word. (''%%<key>C-S-Left</key>%%'')
  * <key>C-PageUp</key> to go one screen page up. (''%%<key>C-PageUp</key>%%'')
  * <key>C-Minus</key> (''%%<key>C-Minus</key>%%'')
  * <key>'any key'</key> to exit. (''%%<key>'any key'</key>%%'')

===== Installation =====

==== With plugin manager ====

Let the manager do the dirty work, just give him this link to eat: {{plugin-keyboard.tar.gz}}

==== Without plugin manager ====

  - Download the plugin: {{plugin-keyboard.tar.gz}}
  - Extract it into your dokuwiki plugin folder (eg ''lib/plugins'')




==== Quickbutton ====

A quickbutton is now inserted into the toolbar of the edit form via a small action plugin. In order for that button to show up, you might first need to purge the cached JavaScript by once calling [[http://www.yoursite.com/path/to/dokuwiki/lib/exe/js.php?edit=1&write=1&purge=1]]. Also, reload your edit form properly to purge any cached toolbar definitions from the browser cache as well.

<del>As the event the plugin reacts on is only available in the [[http://wiki.splitbrain.org/wiki:develonly|Development version]], the //automaticly inserted// quick button is only available in this version as well.</del> For manual installation in prior versions of Dokuwiki -- e.g. in version 20061106 -- in ''inc/toolbar.php'' right after
<code php>
   array(
      'type'   => 'signature',
      'title'  => $lang['qb_sig'],
      'icon'   => 'sig.png',
      'key'    => 'y',
   ),
</code>
add
<code php>
   array(
      'type' => 'format',
      'title' => 'Mark text as key press',
      'icon' => '../../plugins/keyboard/keyboard.png',
      'open' => '<key>',
      'close' => '</key>',
   ),
</code>

==== More key name substitutions & translations ====

  * Create a directory with the two-letter code of your language in ''lib/plugins/keyboard/lang''
  * Copy the file ''lib/plugins/keyboard/lang/de/lang.php'' to this directoy.
  * Edit the file and make your translations.
  * For substitutions that apply for all languages, edit ''lib/plugins/keyboard/lang/en/lang.php'' and make sure you don't override these in the other languages.

~~DISCUSSION~~