SDIAG version 1.

10
==================

The SDIAG library can be used to display stack diagrams of many UserRPL and
SystemRPL commands on the HP49G. The most convenient way to access the stack
diagrams is from within the Editor (e.g.from the command line) of the HP49G,
using Emacs commands. This is explained in the file Emacs.txt. Also, the
Nosy library provides a link to display stack diagrams of entries.

The present document is a brief technical description of the internal workings

of the lib and contains hints on how to add entries to it.

COPYRIGHT and DISCLAIMER

========================

This library is copyright

(c) 2000, 2001, 2002 Carsten Dominik <dominik@astro.uva.nl>

and Denis Martinez <d.martinez@sofrel.com>

and may be distributed freely, provided that this copyright notice

remains unchanged and is distributed with the program. We are not
responsible for whatever this program does to your calculator. Back
up your RAM before using it.

Introduction
------------

SDIAG is a library which contains the stack diagrams more than 4800 SystemRPL
commands, UserRPL commands and ML entries. The diagrams are distributed over
a large number of small and compressed files, so that accessing a specific
diagram is fast and needs little memory.

User level commands

-------------------

SDIAG contains two user level commands to display stack diagrams which can
also be used in programs.

UsrDiag ( $entry -> )

Display the stack diagram for the user command $ENTRY.
Internally, this command prepends `x' to $ENTRY and then
calls Diag.

SysDiag ( $entry -> )

Displays the stack diagram for $entry.

Adding more entries

-------------------

The database is derived from the big entry database for HP48 and 49. The best
way to add entries to SDIAG is to add them to the big database and then
produce a new version of SDAIG.

However, there is an easy way to add a small number of diagrams locally, on

your calculator. Before looking in the library, the commands which display
stack diagrams check for a global variable with name "diagram". If such a
variable exists and is a string, it is searched before the database in the
library.

The format of entries in the database

=====================================

Entries in the database look like this:

xDUP \-> \|^DUP

DUP 1 \-> 1 1
DROP 1 \->
STD \->
Lookup ob test {} \-> nextob T\e\-> ob F
SUB$ $ #start #end \-> $'
POS$ $ $find #start \-> #pos\e\-> #0
GETPTR \m\rSAVPTR in reverse\eClears Carry.
xSREPL $ $find $repl \-> $' %n
xABCUV \apa pb c \-> u v
EDITLINE \o-> RAM Position of cmdline

\|^ is the uparrow character. It indicates a redirection: The stack diagram

for the xDUP entry can be found under DUP.
\e stands for the EURO character, it separates different lines within
a single stack diagram.
\r stands for character 86h, a bold rightarrow. It marks a reference
to another entry in the database.
\a is the greek character alpha, it is used to mark entries for which
the HP49 CAS provides online help.
\m is the greek character mu, and it marks ML entries.
\o is the greek character rho, and it marks RAM entries.
\-> is the rightarrow.

The diagram file

================

If you would like to locally add entries to the database, you need to create a
variable "diagram". This variable must contain a single string with one-line
entry descriptions like the ones shown above. Different entries are separated
by NEWLINE characters. Note that you have to enter Greek mu and alpha and all
the other special characters as characters (using the CHARS command, for
example).

As an example, we will make a diagram file to cover Wolfgang Rautenbergs

KEYMAN library. The first 3 commands IfD, IfL and IfE?P in that library all
take two objects and turn them into a program. ->TO modifies a program but
also accepts any object. A?D either assignes an object to a key, or deletes a
key (empty stack diagram). RclK recalls either the binding of single key, or
a list of all assigned keys. Finally, SA returns an object. Since all these
commands are user level commands (to be used directly, or in UserRPL
programs), we need to precede the names with "x". The diagram file for the
KEYMAN commands could look like this:

"xIfD ob1 ob2 \-> prog

xIfL ob1 ob2 \-> prog
xIfE?P ob1 ob2 \-> prog
x\->TO prog \-> prog'\eob \-> prog
xA?D \->\eob \->
xRclK \-> prog\e\->\e\-> {all}
xSA \-> ob"

Display of stack diagrams

=========================

To save space, the stack diagrams in the database contain as little whitespace
as possible. Before they are displayed, they are formatted to look nice.

- The name of the entry will be displayed in row 1, together with an

identification of the type of the entry (SysRPL, UserRPL or ML). When the
entry in unsupported, the name will be in parenthesis. For example:

_________________________________
|DUP (SysRPL)|
|---------------------------------|
| 1 -> 1 1 |
| |
|______.____.____.____._____._____|
|CAS.H | >1 | >2 | >3 | ob? | OK |
------^----^----^----^-----^-----

- The ML cookie (Greek mu), the RAM cookie (Greek rho) and the CAS cookie
(Greek alpha) are removed.

- The EURO symbol is translated to newline characters.

- All occurrences of the arrow \-> will be aligned, and the lines containing
an arrow will as a whole be centered. For example

Lookup op test comp \-> nextob T <EURO> \-> ob F

will be displayed as

_________________________________
|Lookup (SysRPL)|
|---------------------------------|
| ob test comp -> nextob T |
| -> ob F |
|______.____.____.____._____._____|
|CAS.H | >1 | >2 | >3 | ob? | OK |
------^----^----^----^-----^-----

Lines which don't contain an arrow will start in column zero.

- The following abbreviations will be expanded if they are alone on a line

(between two <EURO> characters).

VS -> Virtual Stack:

RS -> Runstream:

So the following stack diagram

PushVStack&Keep obn..ob1 [B] -> [B] <EURO>VS<EURO> -> [obn..ob1]

will be displayed like this:

_________________________________
 |PushVStack&Keep (SysRPL)|
|---------------------------------|
| obn..ob1 [B] -> [B] |
|Virtual Stack: |
| -> [obn..ob1] |
|______.____.____.____._____._____|
|CAS.H | >1 | >2 | >3 | ob? | OK |
------^----^----^----^-----^-----

- If the stack diagram is wider than the screen, this will be indicated by
an arrow at the end of the line under the entry name, like in this example
for the unsupported entry ^Choose3Index (a "T" after the #idx is off the
screen).

_________________________________
|(^Choose3Index) (SysRPL)|
|-------------------------------->|
|meta $title #pos :handler -> #idx|
| -> F |
| |
|______.____.____.____._____._____|
|CAS.H | >1 | >2 | >3 | ob? | OK |
------^----^----^----^-----^-----

Menu buttons
============

The stack diagram display has a menu with the following options

CAS.H If the entry is a CAS entry (identified by Greek alpha as the

first character of the stack diagram), this button gets you to the
CASCMD help for this entry. If the entry is not CAS, the button
will not be present.

>1 Cross reference to the first word in the stack diagram with
the cross reference cookie (character 86h) before it.

>2 2nd cross reference.

>3 3rd cross reference.

ob? Displays a help screen with explanation of the symbols used

in the stack diagrams.

OK Exit the stack diagram display.

Additional keys:
----------------
Arrow keys: Scroll the stack diagram (if it is too large to fit on
the screen).

Other keys: Any other key exits as well (like the OK menu key).

Internal organization
=====================
SDIAG has separate files for each starting letter of command names. So
commands starting with "a" are in one file, commands starting with "A" are in
another. All commands starting with non-letters (like `!', `$' etc) are
lumped together in a single extra file.

Due to the organization of the command names some starting characters are
very frequent. For example, all FlashPointers start with "^" (there are about
1500 of them) and all UserRPL commands start internally with "x" (there are
hundreds of them). This would lead to a few extremely large files, an
unwanted effect. In order to balance the different files better, the
following steps were taken:

1. Extra files for entry names starting with `#' and `%' since these are the
most frequent non-letters.

2. All FlashPointers, RomPointers and User commands are filed under the
lowercase version of the first letter in the command name which is not `^',
`~', or `x'.

All User commands are filed under their name preceded with `x', even if there
is no SystemRPL entry with that name. For example, FOR is filed as xFOR, even
though xFOR is not a valid extable name.