====== keyboard Plugin ======

---- plugin ----
description: Marks text as keyboard keys
author     : Dokufreaks (previous author: Gina Häußge)
email      : freaks@dokuwiki.org
type       : syntax
lastupdate : 2023-02-23
compatible : Detritus, Elenor Of Tsort, Frusterick Manners, Greebo, Hogfather, Igor, Jack Jackrum
depends    : 
conflicts  : 
similar    : 
tags       : keyboard, odt, pdf

downloadurl: https://github.com/dokufreaks/plugin-keyboard/archive/master.zip
sourcerepo : https://github.com/dokufreaks/plugin-keyboard
bugtracker : https://github.com/dokufreaks/plugin-keyboard/issues
screenshot_img : https://github.com/dokufreaks/plugin-keyboard/raw/master/KeyboardScreenshot.png
----

Should work as-is, no longer actively maintained by original author.

Works well with the [[plugin:dw2pdf|dw2pdf plugin]] and the [[plugin:odt|odt plugin]].

===== Usage =====

Use the tag ''<key>'' to mark some text as keyboad keys. E.g.:

<code>
This displays the keys <key>ALT</key> + <key>H</key>.
</code>

This will create the following output:

----

{{ https://raw.github.com/dokufreaks/plugin-keyboard/master/example/KeyboardPluginXHTMLRendering.png |Example screenshot}}

----

Alternatively the tag ''<kbd>'' can be used in accordance to the HTML element:
<code>
This displays the keys <kbd>ALT</kbd> + <kbd>H</kbd>.
</code>

==== Short form ====

The shorter form to write the key combination ''ALT+H'' is:

<code>
This displays the keys <kbd>ALT+H</kbd>.
</code>

Separator signs for the short form can be ''+'' or ''-''. In both cases the rendered sign between the keys will be a ''+''. So in general it does not make a difference if ''+'' or ''-'' is used. But it does make a difference if you want to include a ''+'' or ''-'' as a key and not as a separator. If you would like to render the key combination ''ALT++'' then you should write: <code><kbd>ALT-+</kbd></code>
If you would like to render the key combination ''ALT+-'' then you should write: <code><kbd>ALT+-</kbd></code>

==== Escape mechanism ====

Since release 2018-08-09 it is possible to surround keys with '...'. All keys enclosed in '...' will be displayed as-is without interpreting ''+'' or ''-'' as separators. Here is an example:

<code>
<kbd>'ALT+H'</kbd>
</code>

This example would display "ALT+H" as a single key instead of two keys: "ALT" + "H".

==== Specify CSS class ====

If you like to vary the look with each given key sequence you can also specify a CSS class like this:
<code><key class="myclass">ALT+H</key></code>

==== Short cuts ====

Some keys like the letter **C** are short cuts which will be expanded to a translated key name. For example **<key>ALT+C</key>** will show the same result as if you entered **<key>ALT+Ctrl</key>**. If you want to suppress this behaviour then include the letter between two **'**. E.g. if you really want to show the letter **C** instead of **Ctrl** then write **<key>ALT+'C'</key>**.

===== Configuration =====

The following configuration options exist:
 
**disable_translation** --- if this option is activated then all translations and short cuts are deactivated. The given keys will be displayed "as-is".

**css_class** --- the CSS class to use if no class is given in the syntax tag. There are two built-in classes:

For the standard look enter:
<code>__keyboard</code>
For a look similar to the MediaWiki keypress template enter:
<code>__keyboard_keypress</code>
You can also enter user defined CSS classes which e.g. could be defined in **conf/userstyle.css**, see [[tips:customizing_templates]].

Some DokuWiki templates like the Bootstrap3 template define an own style for ''kbd'' elements. In this case the **css_class** setting needs to be empty to use the style of the template.

===== Development =====

Changes:
{{rss>https://github.com/dokufreaks/plugin-keyboard/commits/master.atom date}}

===== Add LaTeX support ====

You can enhance this plugin to be used with different LaTeX export plugins. Otherwise the LaTeX export will (most likely) simply skip/ignore the keys.

==== dokutexit support ====

If you want to use this package with [[plugin:dokutexit]], you can easily add latex-support: add the following after line 105 in "syntax.php":

<code php add-this-for-dokutexit-support.php>
        if ($mode == 'latex') {
            list($state, $match) = $data;
            switch ($state) {
                case DOKU_LEXER_ENTER :
                    $renderer->doc .= '\framebox{';
                    break;
                case DOKU_LEXER_UNMATCHED :
                    foreach ($match as $key) {
                        if (substr($key, 0, 1) == "'" and
                          substr($key, -1, 1) == "'" and
                          strlen($key) > 1) {
                            $out[] = $renderer->_xmlEntities(substr($key,1,-1));
                        } else {
                            if (isset($lang[$key])) {
                                $out[] = $lang[$key];
                            } else {
                                $out[] = $renderer->_xmlEntities(ucfirst($key));
                            }
                        }
                    }
                    $renderer->doc .= implode('} + \framebox{', $out);
                    break;
                case DOKU_LEXER_EXIT :
                    $renderer->doc .= '}';
                    break;
            }
            return true;
        }
</code>

==== latexit support ====

If you want to use this package with [[plugin:latexit]], add the following after line 105 in "syntax.php":

<code php add-this-for-latexit-support.php>
        if ($mode == 'latex') {
            list($state, $match) = $data;
            switch ($state) {
                case DOKU_LEXER_ENTER :
                    $renderer->doc .= '\framebox{';
                    break;
                case DOKU_LEXER_UNMATCHED :
                    foreach ($match as $key) {
                        if (substr($key, 0, 1) == "'" and
                          substr($key, -1, 1) == "'" and
                          strlen($key) > 1) {
                            $out[] = $renderer->_latexSpecialChars(substr($key,1,-1));
                        } else {
                            if (isset($lang[$key])) {
                                $out[] = $lang[$key];
                            } else {
                                $out[] = $renderer->_latexSpecialChars(ucfirst($key));
                            }
                        }
                    }
                    $renderer->doc .= implode('} + \framebox{', $out);
                    break;
                case DOKU_LEXER_EXIT :
                    $renderer->doc .= '}';
                    break;
            }
            return true;
        }
</code>

===== Translations =====

The plugin is available in the languages German, English, French, Korean and Chinese.

===== Issues/Requests =====

Please report any issues or requests on the [[https://github.com/dokufreaks/plugin-keyboard/issues|GitHub issue tracker]].