README file for the Papenmeier Driver
=====================================

Version 2.1 (October 2001)

Copyright
=========

This driver is copyrighted under the GNU Public License.  It is free 
software.  See the file 'LICENSE-GPL' for more details.  Feel free to send 
your comments and to report bugs (if any :)) to us at
august.hoerandl@gmx.at or heimo.schoen@gmx.at

Supported Hardware
==================
This driver is supposed to work with all the Papenmeier Terminals.
The driver is able to autodetect the connected terminal.

Connection
==========
This driver supports serial and USB communication.

Running the Driver
==================
To compile and run BRLTTY, please refer to the documentation about 
BRLTTY itself. One note though: when BRLTTY starts, it will display 
on the screen some copyright stuff, current configuration (model and 
firmware version setup) and the device in use.  That information 
may be useful if nothing happens with the braille terminal.


Key Bindings and Status Cells
=============================
The driver is fully configurable - all key bindings and the status cells
can be fully programmed:

The configuration can be done by
- changing the default configuration in the source file brl-cfg.h
  any changes will be distributed to the online help during compile
- edit the config file /etc/brltty/brltty-pm.conf; don't forget to supply 
  a fitting help file

If you don't want to use the config file you can safely remove the
config file /etc/brltty/brltty-pm.conf and use the compiled in
defaults. By default the driver is compiled with the READ_CONFIG
symbol defined.  Without this symbols the code to read the config file
won't be compiled into the driver which yields a driver with a much
smaller size.

Help File:
==========
The online help is generated from the compiled in defaults - it uses
the same syntax as the config file to give the user a short overview of
the status cells and the keymapping.
By default the help command is mapped to the key on the first status cell.

Config File
===========
The configuration file may include the definitions for several terminals.
Look at Papenmeier/brltty-pm.conf and the Papenmeier/*.hlp files for 
examples.

Syntax:
#     Comment to the end of line
name = value   you can use 'is' instead of '='; actually you don't have to
 write '=', 'is' or 'and' at all. The following lines are equivalent:
name = val
name is val
name val

Start a new terminal definition:
identification = NUMBER
the number is the code returned by the terminal on identification 
request; this starts a new terminal defintion - no need to change this info

Info about the terminal - Name and size of the terminal:
terminal = "String to describe the Terminal"
helpfile = "brltty-pm1.hlp"   # name of the helpfile
displaysize = 40       # number of cells  
statuscells = 0        # number of status cells (horizontal or vertical)
frontkeys = 9          # number of keys on the front of the terminal
haseasybar             # terminal has an easybar (EL types)

Terminal settings:
Statusdisplay settings:
there are different display modes:
 flag: left half: line number, right half: no/all bits set - used with
   vertical status cells
 horiz: two digits on the vertical status-display
 number: display two digits in one cell (status on horiz.display)
example: 
status 4 = horiz cursorcol
status 6 = flag tracking
a list of the possible info to display (see brl.h and/or Papenmeier/hlp.auto.h)
current - current line number
row - cursor position - row
col - cursor position - column
tracking - cursor tracking
dispmode - dispmode (text / attribut)
frozen - screen frozen
visible - cursor visible
size - cursor size
blink - cursor blink
capitalblink - capital letter blink
dots - 6 or 8 dots
sound - sound
skip - skip identical lines
underline - attribute underlining
blinkattr - blinking of attribute underlining

Key definition:
status NUMBER     - key on status cell
front NUMBER      - key on the front side of the terminal
routing           - one of the routing keys is pressed
easy DESCR        - easy bar key 
  DESCR may be: left, left2, up, up2, down, down2, right, right2
switch NUMBER     - switches on the left and right side of the 
  display; numbered from 1 (leftmost switch up) to 8 (rightmost switch down)

Modifier key settings:
any key can be defined as a modifier (like the shift or alt key on the 
standard keyboard). 

Input mode:
during inputmode the modifier keys are used to input the 8 dots of a 
character. Attention: the modifiers keys are used to simulate
the different dots, so INPUTMODE or INPUTMODE OFF should be
mapped to a single key.

Commandkey settings:
list of definitions:
  command = key 
  command = modifier and key
The command is executed on keypress; if you specify only modifiers 
the command is executed when the first modifier is released.
For commands which toggle a setting it is possible to add ON or OFF to 
the command to define a predictable state change
  command ON = <as above>
  command OFF = <as above>
A list of the possible commands (the following list is sometimes out of 
date - see brldefs.h and/or Papenmeier/hlp.auto.h for the actual values), the names 
may be used with or without the leading CMD_:
NOOP - do nothing
LNUP - go up one line
LNDN - go down one line
WINUP - go up several lines
WINDN - go down several lines
PRDIFLN - go up to line with different content
NXDIFLN - go down to line with different content
ATTRUP - go up to line with different attributes
ATTRDN - go down to line with different attributes
PRBLNKLN - go to last line of previous paragraph
NXBLNKLN - go to first line of next paragraph
PRSEARCH - search up for content of cut buffer
NXSEARCH - search down for content of cut buffer
TOP - go to top line
BOT - go to bottom line
TOP_LEFT - go to top-left corner
BOT_LEFT - go to bottom-left corner
CHRLT - go left one character
CHRRT - go right one character
HWINLT - go left one half window
HWINRT - go right one half window
FWINLT - go left one full window
FWINRT - go right one full window
FWINLTSKIP - go left to non-blank window
FWINRTSKIP - go right to non-blank window
LNBEG - go to beginning of line
LNEND - go to end of line
HOME - go to cursor
BACK - go to last motion
CSRJMP - route cursor to top-left corner of braille window
CSRJMP_VERT - route cursor to top line of window
CUT_BEG - cut text from top-left corner of braille window
CUT_END - cut text to bottom-right corner of braille window
PASTE - insert cut buffer at cursor
FREEZE - freeze/unfreeze screen
DISPMD - toggle display attributes/text
SIXDOTS - toggle text style 6-dot/8-dot
SLIDEWIN - toggle sliding window on/off
SKPIDLNS - toggle skipping of identical lines on/off
SKPBLNKWINS - toggle skipping of blank windows on/off
CSRVIS - toggle cursor visibility on/off
CSRHIDE_QK - toggle quick hide of cursor
CSRTRK - toggle cursor tracking on/off
CSRSIZE - toggle cursor style underline/block
CSRBLINK - toggle cursor blinking on/off
ATTRVIS - toggle attribute underlining on/off
ATTRBLINK - toggle attribute blinking on/off
CAPBLINK - toggle capital letter blinking on/off
SND - toggle sound on/off
HELP - display driver help
INFO - display status summary
PREFMENU - present preferences menu
PREFSAVE - save preferences
PREFLOAD - reload preferences
SAY - speak current line
SAYALL - speak rest of screen
MUTE - stop speaking immediately
SPKHOME - goto current/last speech position
SWITCHVT_PREV - switch to previous virtual terminal
SWITCHVT_NEXT - switch to next virtual terminal
RESTARTBRL - reinitialize braille driver
RESTARTSPEECH - reinitialize speech driver
INPUTMODE - toggle input mode
Values to be used in combination with "routing":
names may be used with or without the leading CR_:
ROUTEOFFSET - route cursor to character
BEGBLKOFFSET - define the beginning of a block
ENDBLKOFFSET - define the end of a block
SWITCHVT - switch virtual terminal
NXINDENT - find next line not more indented than routing key indicates
PRINDENT - find previous line not more indented than routing key indicates
MSGATTRIB - message attributes of character
Special commands to send keystrokes, 
the names may be used with or without the leading VPK_:
RETURN - send RETURN key
TAB - send TAB key
BACKSPACE - send BACKSPACE key
ESCAPE - send ESCAPE key
CURSOR_LEFT - send CURSOR_LEFT key
CURSOR_RIGHT - send CURSOR_RIGHT key
CURSOR_UP - send CURSOR_UP key
CURSOR_DOWN - send CURSOR_DOWN key
PAGE_UP - send PAGE_UP key
PAGE_DOWN - send PAGE_DOWN key
HOME - send HOME key
END - send END key
INSERT - send INSERT key
DELETE - send DELETE key
FUNCTION - send FUNCTION key
