9 - mousetrap.js

To provide keyboard-driven navigation in my documentation, I use mousetrap.js, a lovely little bit of cross-browser compatible javascript by Craig Campbell that allows, among other things, reliable keyboard navigation of documents.

The canonical source for mousetrap.js may be found here. mousetrap.js is distributed subject to the Apache 2.0 license, which you should definitely read. It is a very permissive and sane license that is decidedly freedom-oriented, much more so than the GPL.

9.1 - Implementing Keyboard Navigation

I include the following global style,  {keynav} , which implements a script, which in turn utilizes mousetrap.js, between the  <HEAD>  and  </HEAD>  tags in the page style:

[gstyle keynav <script src="mousetrap.js" type="text/javascript"></script>
<script type="text/javascript">
Mousetrap.bind(",", onLeft_keyDown,  "keydown");
Mousetrap.bind(".", onRight_keyDown, "keydown");
Mousetrap.bind("i", onIndex_keyDown, "keydown");
Mousetrap.bind("t", onToc_keyDown,   "keydown");
function onLeft_keyDown()  [ls] window.location.href = "[v prevpage]"[rs]
function onRight_keyDown() [ls] window.location.href = "[v nextpage]"[rs]
function onIndex_keyDown() [ls] window.location.href = "indexpage.html"[rs]
function onToc_keyDown()   [ls] window.location.href = "tocpage.html"[rs]

In the  {keynav}  style above, you'll note the use of the escapes  [ls]  and  [rs]  rather than actual { and } characters. This is because within the context of aa_macro, and therefore this documentation system, those characters (as well as [ and ], for which the escapes are  [lb]  and  [rb] ) always have meaning, so if you require them in your output, you must use the escapes.

10 - Key Navigation Display

Everything that needs to be done for the actual keyboard navigation is already done; but the reader needs to be informed about it, and to do it somewhat nicely, I do the following:

First, I include the CSS class for the key representations between the  <HEAD>  and  </HEAD>  tags in the style for the HTML page (which is in this project's Page Style block) using this style:


Which is defined thusly in the project style:

[gstyle csskey <style type="text/css">
.ckey [ls]
      display: inline-block;
  white-space: nowrap;
       border: .1em solid #000000;
border-radius: 5px;
min-width: 1em;
 border-color: #AAAAAA;
   background: #000000; 
 padding-left: 3px;
padding-right: 3px;
        color: #ffffff;

This style provides a very easy way to represent a key:

[gstyle key <span class="ckey">[b]</span>]

I created the key banner at the bottom of each page with this style:

[gstyle keyhints 
<div style="
        clear: both;
       width: 75%;
border-style: solid;
  background: #ffffff;
  text-align: center;
     padding: .5em;
      margin: auto;
[i Keyboard Navigation]
<hr width="75%">
{key ,} Previous Page
{key .} Next Page
{key t} TOC
{key i} Index

Then to use it, I emplace  {keyhints}  at the bottom of the page content. Here's the entire page style for context; you can easily see where  {keyhints}  is placed after  [b] :

[gstyle page 
               <div style="font-family: monospace;">[b]</div>
Keyboard Navigation
, Previous Page . Next Page t TOC i Index

Valid HTML 4.01 Loose

This manual was generated with wtfm