Skip to content

Commit

Permalink
documentation: Add DM-32 section for keyboard layout.
Browse files Browse the repository at this point in the history 
Add a section that explains why the DM-32 keyboard layout is not
really usable without an overlay.

This is part of #450.

Signed-off-by: Christophe de Dinechin <christophe@dinechin.org>
  • Loading branch information
@c3d
c3d committed Oct 22, 2023
1 parent 1679e1d commit 0c83cc4
Show file tree
Hide file tree
Showing 3 changed files with 155 additions and 191 deletions.
104 changes: 77 additions & 27 deletions doc/0-Overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,19 +36,25 @@ existing DM42 physical hardware.
<!--- DM42 --->
Ideally, DB48X should be fully usable without a
keyboard overlay. though one is [being worked on](../Keyboard-Layout.png).

Compared to the original HP48, the DM42 has a much larger screen, but no
annunciators (it is a fully bitmap screen). It has a keyboard with dedicated
soft-menu (function) keys, but only one shift key (whereas the HP48 has two),
lacks a dedicated alpha key, does not provides left or right arrow keys (only up
and down), and has no space key (_SPC_ on the HP48).
<!--- !DM42 --->
<!--- DM32 --->
The DM32 keyboard layout is really different compared to the DB48X expected
layout. For example, the DM32 does not have unshifted arrow keys, and has two
shift keys. For that reason, when running DB48X on a DM32, it is highly
recommended to use a [keyboard overlay](../Keyboard-Layout.png).
<!--- !DM32 --->

Compared to the original HP48, the DM42 has a much larger screen, but no
Compared to the original HP48, the DM32 has a much larger screen, but no
annunciators (it is a fully bitmap screen). It has a keyboard with dedicated
soft-menu (function) keys, but only one shift key (whereas the HP48 has two),
lacks a dedicated alpha key, does not provides left or right arrow keys (only up
and down), and has no space key (_SPC_ on the HP48).
soft-menu (function) keys, but no arrow keys (whereas the HP48 has four),
lacks a dedicated alpha key, and has no space key (_SPC_ on the HP48).
<!--- !DM32 --->



## Keyboard interaction
Expand All @@ -64,12 +70,16 @@ calculator compared to the HP48:
<!--- !DM42 --->

<!--- DM32 --->
* When running DB50X on the DM32, the blue 🟦 key cycles between three states,
*Shift*, *Right Shift* and no shift. The yellow 🟨 shift key is actually used
as a down/right cursor key, and the _XEQ_ key is used as an up/left cursor
key. This remapping of keys appears necessary because RPL calculators like the
HP48 have a rather full keyboard even with two shift keys, and absolutely need
at least two cursor keys.
* When running DB50X on the DM32, the blue shift key cycles between three
states, *Shift* (shown in the documentation as 🟨), *Right Shift* (shown in
the documentation as 🟦) and no shift. The physical yellow shift key is
actually used as a down/right cursor key, and will be shown as _▶︎_ in the rest
of this document. Similarly, the _XEQ_ key is used as an up/left cursor key,
and will be shown as _◀︎_ in the rest of this document. This remapping of keys
appears necessary because RPL calculators like the HP48 are command-line
oriented and absolutely need at least two unshifted cursor keys. Sacrificing a
physical shift key while preserving two shifted function seems like the best
compromise.
<!--- !DM32 --->

* The less-frequently used functions can be accessed after a
Expand All @@ -83,13 +93,17 @@ calculator compared to the HP48:
frequently than on the HP42, making it quickly accessible seems important, so
there are [three distinct ways to activate it](#alpha-mode).

<!--- DM42 --->
* The _▲_ and _▼_ keys move the cursor *left* and *right* while editing
instead of *up* and *down*. These cursor movements are much more useful for a
text-based program editing as found in RPL.
text-based program editing as found in RPL. In the rest of this document,
they are described as _◀︎_ and _▶︎_ respectively.
<!--- !DM42 --->

* Using 🟨 _▲_ and 🟨 _▼_ moves the cursor up and down. When not editing, _▲_
and _▼_ behave like on the HP48, i.e. _▲_ enters the *interactive stack* (not
yet implemented) and _▼_ edits the object on the first level of the stack.
* Using 🟨 _◀︎_ and 🟨 _▶︎_ moves the cursor up and down. When not editing, _▶︎_
and _▶︎_ behave like _▲_ and _▼_ on the HP48, i.e. _◀︎_ enters the *interactive
stack* (not yet implemented) and _▶︎_ edits the object on the first level of
the stack.

* Long-pressing arrow keys, the _←_ (also known as *Backspace*) or text entry
keys in Alpha mode activates auto-repeat.
Expand Down Expand Up @@ -118,10 +132,10 @@ There are three ways to enter *Alpha* mode:
between *Alpha* _ABC_ and *Normal* entry modes, and cannot be used to type
lowercase characters.

* The third method is to hold one of the arrow keys _▲_ or _▼_ *while* typing on
* The third method is to hold one of the arrow keys _◀︎_ or _▶︎_ *while* typing on
the keyboard. This is called *transient alpha mode* because *Alpha* mode ends
as soon as the arrow key is released. Using _▲_ enters uppercase characters,
while _▼_ uses lowercase characters.
as soon as the arrow key is released. Using _◀︎_ enters uppercase characters,
while _▶︎_ uses lowercase characters.

There is no equivalent of the HP48's "single-Alpha" mode. Alpha mode is either
_transient_ (when you hold one of the arrow keys) or _sticky_ (with 🟨 _ENTER_
Expand All @@ -143,8 +157,10 @@ gives a variety of special characters.

![DB48X keyboard layout](keyboard.png)

Some keys that have little use or no direct equivalent for RPL are remapped
as follows:
<!--- DM42 --->
If you are using DB48X on a DM42, it is almost possible to do it without a
keyboard overlay. Some keys that have little use or no direct equivalent for RPL
are remapped as follows:

* _Σ+_ is used to call [ToolsMenu](#ToolsMenu), which select a menu based on
context, notably the content of the stack.
Expand All @@ -153,9 +169,15 @@ as follows:
previous menu.

* 🟦 _Σ+_ selects [MainMenu](#MainMenu), the top-level menu giving access
to all other menus and features in DB48X (see also the [Catalog](#catalog)
to all other menus and features in DB48X (see also the [Catalog](#CatalogMenu)
feature).

* _LOG_ and _EXP_ keys are swapped. The HP42 has _LOG_ and _LN_ with shifted
_10^X_ and _E^X_. DB48X has _E^X_ and _LN_ with shifted _10^X_ and _LOG_, so
that the more frequently used mathematical functions are available without
shifting. Note that in the future, full keyboard remapping similar to the HP41
or HP48 will allow you to change that if you prefer.

* _XEQ_ opens an algebraic expression, i.e. it shows `''` on the command-line
and switches to equation entry. It can be remembered as *Execute Equation* and
can be used to evaluate expressions in [algebraic mode](#algebraic-mode)
Expand Down Expand Up @@ -208,7 +230,7 @@ as follows:
various items, including [ClearStack](#ClearStack) and
[ClearMenu](#ClearMenu).

* _SST_ and _BST_ (🟨 _▲_ and _▼_) move the cursor *up* and *down* in the text
* _SST_ and _BST_ (🟨 _◀︎_ and 🟨 _▶︎_) move the cursor *up* and *down* in the text
editor. In direct mode, _BST_ selects the *Best* editor for the object, and
*Sst* selects single-step evaluation.

Expand Down Expand Up @@ -271,17 +293,45 @@ as follows:
* _PRGM_ (🟨 _R/S_) inserts the delimiters for an RPL program, `«` and `»`,
while 🟦 _R/S_ inserts the list delimiters, `{` and `}`.

* _CATALOG_ (🟨 _+_) shows a complete context-sensitive catalog of all
available functions, and enables auto-completion using the soft-menu
* _CATALOG_ (🟨 _+_) shows a complete context-sensitive [catalog](#CatalogMenu)
of all available functions, and enables auto-completion using the soft-menu
keys. Note that the `+` key activates the catalog while in *Alpha* mode.

* _HELP_ (🟦 _+_) activates the context-sensitive help system.
<!--- !DM42 --->

<!--- DM32 --->
Using DB50X with the DM32 is quite difficult without a keyboard overlay.

In particular, an unfortunate difference between the DM32 and the keyboard
layout used by DB50X is that the placement of all letters after `M` is shifted
by one position on the keyboard, and the first row of scientific functions
(starting with square root and ending with _Σ+_) is inconsistent. The reason is
that the layout for DB50X is heavily based on the DM-42 model.

Also, while the DM32 has two shift keys, a blue and a yellow one, it lacks
dedicated cursor movement arrow keys, a limitation that is visible in the
calculator's firmware menus. While the two arrow shift keys would be welcome,
not having arrow keys for cursor movement is just not an option. As a result,
only the blue shift key is kept as a shift key, and the yellow shift key is
converted to an arrow key, along with the DM32 _XEQ_ key.

<!--- !DM32 --->

In the rest of this document, the shift key is referred to as 🟨, and pressing
it twice is referred to as 🟦, irrespective of the appearance of the physical
shift key on your particular hardware.

DB48X keyboard overlays for SwissMicros calculators are
[already available](https://www.hpmuseum.org/forum/thread-20113.html).


## Soft menus

The DM42 has 6 dedicated soft-menu keys at the top of the keyboard. Most of the
advanced features of DB48X can be accessed through these soft menus.
advanced features of DB48X can be accessed through these soft menus. Soft menu
keys have no label on the physical calculator, but in this documentation, they
may sometimes be referred to as _F1_ through _F6_.

Menus are organized internally as a hierarchy, where menus can refer to other
menus. A special menu, [MainMenu](#MainMenu), accessible via the 🟦 _Σ+_,
Expand All @@ -299,7 +349,7 @@ a `▶︎`, and 🟨 _F6_ turns into `◀`︎. These keys can be used to
navigate across the available menu entries. This replaces the _NXT_ and _PREV_
keys on HP calculators.

The `Variables` menu (_RCL_ key) is special in the sense that:
The [VariablesMenu](#VariablesMenu) (_RCL_ key) is special in the sense that:

* Selecting an entry *evaluates* that menu entry, for example to run a program

Expand Down Expand Up @@ -525,7 +575,7 @@ To navigate the help on the calculator, use the following keys:
_F6_, correspond to the functions shown in the six labels at the bottom of the
screen.

* While the help is shown, the keys _▼_ and _▲_ on the keyboard scroll
* While the help is shown, the keys _◀︎_ and _▶︎_ on the keyboard scroll
through the text.

* The _F1_ key returns to the [Home](#overview) (overview).
Expand Down
52 changes: 36 additions & 16 deletions help/db48x.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ lacks a dedicated alpha key, does not provides left or right arrow keys (only up
and down), and has no space key (_SPC_ on the HP48).



## Keyboard interaction

The keyboard differences force us to revisit the user interaction with the
Expand All @@ -67,11 +68,13 @@ calculator compared to the HP48:

* The _▲_ and _▼_ keys move the cursor *left* and *right* while editing
instead of *up* and *down*. These cursor movements are much more useful for a
text-based program editing as found in RPL.
text-based program editing as found in RPL. In the rest of this document,
they are described as _◀︎_ and _▶︎_ respectively.

* Using 🟨 _▲_ and 🟨 _▼_ moves the cursor up and down. When not editing, _▲_
and _▼_ behave like on the HP48, i.e. _▲_ enters the *interactive stack* (not
yet implemented) and _▼_ edits the object on the first level of the stack.
* Using 🟨 _◀︎_ and 🟨 _▶︎_ moves the cursor up and down. When not editing, _▶︎_
and _▶︎_ behave like _▲_ and _▼_ on the HP48, i.e. _◀︎_ enters the *interactive
stack* (not yet implemented) and _▶︎_ edits the object on the first level of
the stack.

* Long-pressing arrow keys, the _←_ (also known as *Backspace*) or text entry
keys in Alpha mode activates auto-repeat.
Expand Down Expand Up @@ -100,10 +103,10 @@ There are three ways to enter *Alpha* mode:
between *Alpha* _ABC_ and *Normal* entry modes, and cannot be used to type
lowercase characters.

* The third method is to hold one of the arrow keys _▲_ or _▼_ *while* typing on
* The third method is to hold one of the arrow keys _◀︎_ or _▶︎_ *while* typing on
the keyboard. This is called *transient alpha mode* because *Alpha* mode ends
as soon as the arrow key is released. Using _▲_ enters uppercase characters,
while _▼_ uses lowercase characters.
as soon as the arrow key is released. Using _◀︎_ enters uppercase characters,
while _▶︎_ uses lowercase characters.

There is no equivalent of the HP48's "single-Alpha" mode. Alpha mode is either
_transient_ (when you hold one of the arrow keys) or _sticky_ (with 🟨 _ENTER_
Expand All @@ -125,8 +128,9 @@ gives a variety of special characters.

![DB48X keyboard layout](keyboard.png)

Some keys that have little use or no direct equivalent for RPL are remapped
as follows:
If you are using DB48X on a DM42, it is almost possible to do it without a
keyboard overlay. Some keys that have little use or no direct equivalent for RPL
are remapped as follows:

* _Σ+_ is used to call [ToolsMenu](#ToolsMenu), which select a menu based on
context, notably the content of the stack.
Expand All @@ -135,9 +139,15 @@ as follows:
previous menu.

* 🟦 _Σ+_ selects [MainMenu](#MainMenu), the top-level menu giving access
to all other menus and features in DB48X (see also the [Catalog](#catalog)
to all other menus and features in DB48X (see also the [Catalog](#CatalogMenu)
feature).

* _LOG_ and _EXP_ keys are swapped. The HP42 has _LOG_ and _LN_ with shifted
_10^X_ and _E^X_. DB48X has _E^X_ and _LN_ with shifted _10^X_ and _LOG_, so
that the more frequently used mathematical functions are available without
shifting. Note that in the future, full keyboard remapping similar to the HP41
or HP48 will allow you to change that if you prefer.

* _XEQ_ opens an algebraic expression, i.e. it shows `''` on the command-line
and switches to equation entry. It can be remembered as *Execute Equation* and
can be used to evaluate expressions in [algebraic mode](#algebraic-mode)
Expand Down Expand Up @@ -190,7 +200,7 @@ as follows:
various items, including [ClearStack](#ClearStack) and
[ClearMenu](#ClearMenu).

* _SST_ and _BST_ (🟨 _▲_ and _▼_) move the cursor *up* and *down* in the text
* _SST_ and _BST_ (🟨 _◀︎_ and 🟨 _▶︎_) move the cursor *up* and *down* in the text
editor. In direct mode, _BST_ selects the *Best* editor for the object, and
*Sst* selects single-step evaluation.

Expand Down Expand Up @@ -253,17 +263,27 @@ as follows:
* _PRGM_ (🟨 _R/S_) inserts the delimiters for an RPL program, `«` and `»`,
while 🟦 _R/S_ inserts the list delimiters, `{` and `}`.

* _CATALOG_ (🟨 _+_) shows a complete context-sensitive catalog of all
available functions, and enables auto-completion using the soft-menu
* _CATALOG_ (🟨 _+_) shows a complete context-sensitive [catalog](#CatalogMenu)
of all available functions, and enables auto-completion using the soft-menu
keys. Note that the `+` key activates the catalog while in *Alpha* mode.

* _HELP_ (🟦 _+_) activates the context-sensitive help system.


In the rest of this document, the shift key is referred to as 🟨, and pressing
it twice is referred to as 🟦, irrespective of the appearance of the physical
shift key on your particular hardware.

DB48X keyboard overlays for SwissMicros calculators are
[already available](https://www.hpmuseum.org/forum/thread-20113.html).


## Soft menus

The DM42 has 6 dedicated soft-menu keys at the top of the keyboard. Most of the
advanced features of DB48X can be accessed through these soft menus.
advanced features of DB48X can be accessed through these soft menus. Soft menu
keys have no label on the physical calculator, but in this documentation, they
may sometimes be referred to as _F1_ through _F6_.

Menus are organized internally as a hierarchy, where menus can refer to other
menus. A special menu, [MainMenu](#MainMenu), accessible via the 🟦 _Σ+_,
Expand All @@ -281,7 +301,7 @@ a `▶︎`, and 🟨 _F6_ turns into `◀`︎. These keys can be used to
navigate across the available menu entries. This replaces the _NXT_ and _PREV_
keys on HP calculators.

The `Variables` menu (_RCL_ key) is special in the sense that:
The [VariablesMenu](#VariablesMenu) (_RCL_ key) is special in the sense that:

* Selecting an entry *evaluates* that menu entry, for example to run a program

Expand Down Expand Up @@ -507,7 +527,7 @@ To navigate the help on the calculator, use the following keys:
_F6_, correspond to the functions shown in the six labels at the bottom of the
screen.

* While the help is shown, the keys _▼_ and _▲_ on the keyboard scroll
* While the help is shown, the keys _◀︎_ and _▶︎_ on the keyboard scroll
through the text.

* The _F1_ key returns to the [Home](#overview) (overview).
Expand Down

0 comments on commit 0c83cc4

Please sign in to comment.