Tutorial: Reference shortcuts from 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.

Prepare keymap file

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>

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

Configure project to use the keymap file

Open cfg/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 hotkey defined for this action depending on the selected layout. For example:

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

Press Ctrl+C to copy.

Last modified: 27 November 2023