Writerside Help

Shortcuts

Most software products provide useful key combinations for common actions. It may be a good idea to mention these shortcuts in your documentation to educate your readers and help them be more productive.

Use the <shortcut> element to specify a keyboard shortcut, either directly or by referencing it from a keymap file.

<p>Press <shortcut>Ctrl+C</shortcut> to copy.</p>

Press Ctrl+C to copy.

<p>Press <shortcut key="$Copy"/> to copy.</p>

Press Ctrl+C to copy.

Reference shortcuts from a keymap file

You can define shortcuts for various actions in a keymap file and then reference them in your documentation by IDs. This tutorial describes how to configure the keymap file for your documentation project.

  1. Prepare the keymap file either with a script that extracts the mapping between action IDs and their shortcuts or create it manually.

    Here is an example keymap file that defines three layouts and two actions:

    <?xml version="1.0" encoding="UTF-8"?> <keymap id="my_keymap"> <layouts> <layout name="Windows" platform="PC"/> <layout name="macOS" platform="MAC"/> <layout name="Linux" platform="PC"/> </layouts> <actions> <action id="$Copy"> <description>Copy</description> <shortcut layout="Windows">Ctrl+C</shortcut> <shortcut layout="macOS">⌘ C</shortcut> <shortcut layout="Linux">Ctrl+C</shortcut> </action> <action id="$Paste"> <description>Paste</description> <shortcut layout="Windows">Ctrl+V</shortcut> <shortcut layout="macOS">⌘ V</shortcut> <shortcut layout="Linux">Ctrl+V</shortcut> </action> </actions> </keymap>

  2. Save this file in the help module root next to writerside.cfg.

  3. Open buildprofiles.xml and use the <shortcuts> element to specify the keymap file and the list of layouts that you want to appear in the switcher in your rendered help. For example, if you named the keymap file keymap.xml and want your readers to switch between the Windows and macOS keymaps, add the following:

    <shortcuts> <src>keymap.xml</src> <layout name="Windows" display-name="Windows"/> <layout name="macOS" display-name="macOS"/> </shortcuts>

    Now you can reference actions using the key attribute of the <shortcut> element to render the keyboard combination defined for this action depending on the selected layout. For example:

    <p>Press <shortcut key="$Copy"/> to copy.</p>
Last modified: 14 May 2024
CodeTooltips