	qodem release 0.3.2

These are the release notes for qodem version 0.3.2.

WHAT IS QODEM?

  Qodem is a from-scratch clone implementation of the Qmodem(tm)
  communications program made popular in the days when Bulletin Board
  Systems ruled the night.  Qodem emulates the dialing directory and
  the terminal screen features of Qmodem(tm) over both modem and
  third-party-mediated Internet connections.

  Qodem is distributed under the GNU General Public License - see the
  accompanying COPYING file for more details.

  Qmodem(tm) was last distributed by Mustang Software, Inc. (MSI).
  Qmodem(tm) was acquired by Quintus when it purchased MSI, and its
  current legal status is limbo.  Quintus went bankrupt shortly after
  the MSI acquisition and members of both companies' Boards of
  Directors are involved in a class-action lawsuit regarding the MSI
  acquisition.  The Qodem team is currently seeking any party with
  rights to any version of the Qmodem(tm) help text who may be
  interested in licensing the text for use in Qodem.

IMPORTANT NOTES:


  Please open bugs on the Qodem project page on SourceForge.net:
  http://sourceforge.net/tracker/?group_id=79838&atid=557898

INTENDED AUDIENCE

  Qodem is designed to help the following kinds of people:

    * System administrators who need to occasionally transfer files
      through a connection spanning multiple firewalls.

    * Users of telnet/ssh BBSes who would like to use emulations
      appropriate for a slow link such as Avatar.

    * Casual online MUD/MUSH'ers who want to capture their sessions
      for later review.

    * Console users who want a better scrollback capability without
      having to resort to an X-based emulator.

  However, Qodem is NOT meant for everyone.  The following audiences
  in particular should look to other tools:

    * System administrators who have complex network scripting needs.
      They should instead refer to mature tools like expect, netcat,
      ssh, or roll their own with Perl or shell scripts.

    * Serious online MUD/MUSH'ers who need complex interactive macros.
      They should instead refer to specialized clients like tintin++,
      TinyFugue, Spod, etc.

    * Those who need absolutely perfect VT100-ish emulation including
      true double-width and double-height character glyphs and printer
      support.  They should instead refer to more mature
      fully-graphical emulators like XTerm, Kermit 95, Reflection,
      etc.  (Although Qodem has passed many more VTTEST scenarios than
      Qmodem(tm).)

WHY A CONSOLE-BASED TERMINAL EMULATOR?

  "Why not?"  :-)

  More seriously, Qodem has several advantages over the native console
  or the typical (except for Xterm) "local shell" X-based emulator.

  First, Qodem strives to understand the emulation of its supported
  terminals as well as possible within the text character-cell
  metaphor, so Qodem can understand and respond to remote applications
  that the local console/emulator might not handle.  For instance,
  Qodem can pass 'vttest's VT52 sub-mode test, whereas the raw Linux
  2.6.32 console cannot.  This means if you open a local shell inside
  Qodem and run an application that uses those VT52 extensions under
  VT100 (a very unusual application) you will get the correct output
  and can use that application.  If you tried to run it directly from
  the Linux console, you would be greatly disappointed in the results.
  Qodem also understands Avatar, ANSI.SYS, and can even play "ANSI
  Music" on the raw Linux console by using the private PC speaker
  control sequences.

  Second, Qodem provides a lot of X-based emulator-isms to the text
  console: scrollback, screen dump, capture, etc.  These functions are
  very handy when you work professionally at the console.

  Third, Qodem provides access to X/Y/Zmodem and Kermit upload and
  download protocols over almost any interactive network link (via
  local shell if nothing else).  This is extremely useful for
  quick-and-dirty file transfers when firewalls are blocking the
  standard protocols.

  Fourth, Qodem translates the character sets of the remote systems
  into Unicode in a manner similar to GNU screen.  This allows modern
  systems to see BBS-era screens as they were originally intended, and
  also supports the graphical glyphs for other emulations.

  Finally, Qodem hopes to bundle all of this function inside a
  pleasant environment with some eye appeal.

CAVEATS

  From version 0.1.3 on, Qodem now requires a Unicode-capable Linux
  console or X emulator to look right.  For the Linux console, the
  default settings for most Linux distributions should work well.
  Under X11, UXTerm, rxvt-unicode, and Konsole work well.

  GNU Emacs may look wrong in ANSI emulation when Line Wrap is
  disabled.

  Most BBS programs assume a display with 80x24 dimensions.  Qodem by
  default sets the right margin to column 80 for ANSI, Avatar, and TTY
  emulations.  Changing "80_columns = true" to "80_columns = false" in
  qodemrc will cause Qodem to use the real right margin.

  The backspace key is always mapped to DEL (0x7F) in VT220 emulation
  to match the keyboard of a real VT220.  You can send a true
  backspace (0x08, ^H) by pressing Ctrl-H.

  Function keys beyond F4 in VT100/VT102 emulation may not work as
  expected.  Qodem uses a common convention that F5 is "<ESC>Ot", F6
  is "<ESC>Ou", etc.  Some programs understand this convention.  Those
  that don't will usually understand "<ESC><number>", where <number>
  is a number from 5 to 0, to mean F5 through F10.  You can get this
  effect in Qodem by typing ESC <number>, or by switching to Doorway
  Mode and typing Alt-<number> (or Meta-<number>).

  In VT100, VT102, and LINUX emulations, some programs (like minicom
  and Midnight Commander) send the DECCOLM sequence (<ESC>[?3l) when
  exiting, putting the emulation into 80-column mode.  Resetting the
  emulation via Alt-G <pick emulation> <enter 'y'> will restore the
  default right margin.

  Even though the function key editor window has space for the numeric
  keypad keys, they are not yet supported.  Unix-like consoles do not
  differentiate perfectly between numeric keypad keys and regular
  console keys.

  ASCII uploads may hang if the remote end can't keep up.  For
  instance, using 'vi' to create a large file and ASCII uploading the
  contents may hang after a few kilobytes.  'cat > filename' usually
  works fine.

  ASCII downloads will process the TAB character (0x09) as a control
  character, causing it to expand to the appropriate number of
  spaces.

  Malformed escape sequences might "freeze" LINUX or VTxxx emulation.
  (For example, receiving a 0x90 character causes VT102 to look for a
  DCS sequence.  If the DCS sequence is not properly terminated the
  emulation won't recover.)  Resetting the current emulation will
  restore the console function.

  KEY_SUSPEND is usually mapped to Ctrl-Z and used to suspend the
  local program ('qodem').  If Qodem sees KEY_SUSPEND it will assume
  the user typed Ctrl-Z and meant to pass that to the remote side.

  On Ymodem downloads, if the file exists it will be appended to.

  Xmodem and Ymodem downloads from hosts that use the rzsz package
  might need to have stderr redirected to work correctly, for example
  'sb filename 2>/dev/null' .

  When sending files via Zmodem to HyperTerminal, if the HyperTerminal
  user clicks "Skip file" then the transfer will stall.  This appears
  to be due to two separate bugs in HyperTerminal: 1) When the user
  clicks "Skip File", HyperTerminal sends a ZRPOS with position==file
  size, Qodem responds by terminating the data subpacket with ZCRCW,
  which HyperTerminal responds to with ZACK, however the ZACK contains
  an invalid file position.  2) Qodem ignores bug #1 and sends ZEOF,
  to which HyperTerminal is supposed to respond with ZRINIT, however
  HyperTerminal hangs presumably because it is expecting the ZEOF to
  contain a particular file position, however the position it desires
  is neither the true file size nor the value it returned in the ZACK.

  Kermit receive mode by default handles file collisions by saving to
  a new file (SET FILE COLLISION RENAME / WARN file access Attribute).
  It supports the APPEND file access Attribute but disregards the
  SUPERSEDE file access Attribute.

  Alt-A Translate Tables are only honored for 7-bit characters for
  L_UTF8 and X_UTF8 emulations.

SCRIPT SUPPORT

  Qodem has an entirely different method for supporting scripts than
  Qmodem(tm).

  Qodem does not have its own scripting language.  Instead, any
  program that reads and writes to the standard input and output can
  be run as a Qodem script:

    * Characters sent from the remote connection are visible to the
      script in its standard input.

    * Characters the script emits to its standard output are passed on
      the remote connection.

    * Messages to the standard error are reported to the user and also
      recorded in the session log.

  Since scripts are communicating with the remote system and not Qodem
  itself, they are unable to script Qodem's behavior, e.g. change the
  terminal emulation, hangup and dial another phonebook entry,
  download a file, etc.  However, they can be written in any language,
  and they can be tested outside Qodem.

  Scripts replace the user, and as such have similar constraints:

    * Script standard input, output, and error must all be in UTF-8
      encoding.

    * Scripts should send carriage return (0x0D, or \r) instead of new
      line (0x0A, or \n) to the remote side - the same as if a user
      pressed the Enter key.  They should expect to see either bare
      carriage return (0x0D, or \r) or carriage return followed by
      newline (0x0D 0x0A, or \r\n) from the remote side.

    * Input and output translate byte translation (the Alt-A Translate
      Tables) are honored for scripts.

    * While a script is running:
          - Zmodem and Kermit autostart are disabled.
          - Keyboard function key macros are disabled.
          - Qodem functions accessed through the Alt-character
            combinations and PgUp/PgDn are unavailable.
          - Pressing Alt-P will pause the script.

    * While a script is paused:
          - The script will receive nothing on its standard input.
          - Anything in the script's standard output will be held
            until the script is resumed.
          - The script process will not be signaled; it may continue
            running in its own process.
          - The only Alt-character function recognized is Alt-P to
            resume the script.  All other Alt- keys will be ignored.
          - Keys pressed will be sent directly to the remote system.
          - Keyboard function key macros will work.

  Scripts are launched in two ways:

    * In TERMINAL mode, press Alt-F and enter the script filename.
      The script will start immediately.

    * In the phonebook, add a script filename to a phonebook entry.
      The script will start once that entry is connected.

  Script command-line arguments can be passed directly in both the
  Alt-F script dialog and the phonebook linked script field.  For
  example, pressing Alt-F and entering "my_script.pl arg1" will launch
  my_script.pl and with its first command-line argument ($ARGV[0] in
  Perl) set to "arg1".

DEVIATIONS FROM QMODEM(tm)

  The default emulation for raw serial and command line connections is
  VT102.

  If the screen size is smaller than 80 columns by 25 lines, a control
  sequence is emitted to resize the window to at least 80x25.  This
  solves an important class of defects under X11-based emulators, but
  may cause problems on consoles that cannot be resized this way.

  The IBM PC ALT and CTRL + <function key> combinations do not work
  through the curses terminal library.  CTRL-Home, CTRL-End,
  CTRL-PgUp, CTRL-PgDn, Shift-Tab, and ALT-Up have been given new key
  combinations.

  The F2, F4 and F10 function keys are often co-opted by modern
  desktop environments and unavailable for qodem.  F2 and F10 are
  still supported, but also have additional keys depending on
  function.  Most of the time space bar can be used for F2 and the
  Enter key for F10.  The status bar will show the alternate
  keystrokes.  Since F4 is currently only used to clear the Batch
  Entry Window, no alternative keystroke is provided.

  The ESCAPE key can have a long delay (up to 1 second) under some
  installations of curses.  It is still supported, but the backtick
  (`) can also be used for faster response time.  See ESCDELAY in the
  curses documentation.

  The program settings are stored in a text file usually called
  $HOME/.qodem/qodemrc.  They are hand-edited by the user rather than
  another executable ala QINSTALL.EXE.  The Alt-N Configuration
  command loads the file into an editor for convenience.

  The batch entry window is a simple form permitting up to twenty
  entries, each with a long filename.  Next to each entry is the file
  size.  The Qmodem(tm) screen was limited to three directories each
  containing up to twenty 8.3 DOS filenames, and did not report file
  sizes.  The F3 "Last Found" function is not supported since many
  systems use long filenames.

  The upload window for Ymodem, Zmodem, and Kermit contains a second
  progress indicator for the batch percentage complete.

  Alt-X Exit has only two options yes and no.  Qmodem(tm) offers a
  third (exit with DTR up) that cannot be implemented using Linux-ish
  termios.

  External protocols are not (yet?) supported.

  Some functions are different in TERMINAL mode:

      Key      Qodem function         Qmodem(tm) function
      ----------------------------------------------------------
      Alt-L    Log View               Change drive
      Alt-O    Modem Config           Change directory
      Alt-2    Backspace/Del Mode     80x25 (EGA/VGA)
      Alt-3    Line Wrap              Debug Status Info
      Alt-4    Display NULL           80x43/50 (EGA/VGA)
      Alt-9    Serial Port            Printer Echo
      Alt-P    Capture File           COM Parameters
      Alt-K    Send BREAK             Change COM Port
      Alt-Y    COM Parameters         -
      Alt-,    ANSI Music             -
      Alt-\    Compose Key            -
      Alt-;    Codepage               -

  The Phone Book stores an arbitrary number of entries, not the
  hard-coded 200 of Qmodem(tm).

  The directory view popup window allows up to 20 characters for
  filename, and the Unix file permissions are displayed in the
  rightmost column.

  The directory browse window behaves differently.  Scrolling occurs a
  full page at a time and the first selected entry is the first entry
  rather than the first file.  Also, F4 can be used to toggle between
  showing and hiding "hidden files" (dotfiles) - by default dotfiles
  are hidden.

  The phonebook displays the fully-qualified filename rather than the
  base filename.

  VT100 escape sequences may change terminal settings, such as line
  wrap, local echo, and duplex.  The original settings are not
  restored after leaving VT100 emulation.

  DEBUG_ASCII and DEBUG_HEX emulations are not supported.  Qodem
  instead offers a DEBUG emulation that resembles the output of a
  programmer's hex editor: a byte offset, hexadecimal codes, and a
  region of printable characters.

  TTY emulation is actually a real emulation.  The following control
  characters are recognized: ENQ, BEL, BS, HT, LF, VT, FF, CR.  Also,
  underlines that would overwrite characters in a typical character
  cell display will actually underline the characters.  For example,
  A^H_ ('A' backspace underline) will draw an underlined 'A' on a
  console that can render underlined characters.

  ANSI emulation supports more codes than ANSI.SYS.  Specifically, it
  responds to DSR 6 (Cursor Position) which many BBSes used to
  "autodetect" ANSI, and it also supports the following ANSI X3.64
  functions: ICH, DCH, IL, DL, VPA, CHA, CHT, and REP.  It detects and
  discards the RIPScript auto-detection code (CSI !) to maintain a
  cleaner display.

  The "Tag Multiple" command in the phonebook does not support the
  "P<prefix><number><suffix>" form of tagging.  Number prefixes and
  suffixes in general are not supported.  Also, text searching in both
  "Tag Multiple" and "Find Text/Find Again" is case-insensitive.

  The "Set Emulation" function has the ability to reset the current
  emulation.  For example, if Qodem is in ANSI emulation, and you try
  to change to ANSI emulation, a prompt will appear asking if you want
  to reset the current emulation.  If you respond with 'Y' or 'y', the
  emulation will be reset, otherwise nothing will change.  This is
  particularly useful to recover from a flash.c-style of attack.

  "WideView" mode in the function key editor is not supported.

  "Status Line Info" changes the status line to show the
  online/offline state, the name of the remote system (in the
  phonebook), and the current time.  Qmodem(tm) showed the name of the
  system, the phone number, and the connect time.

  The scripting language is entirely different.  Qodem has no plans to
  support Qmodem(tm) or QmodemPro(tm) scripts.

  Qmodem(tm) had several options to control Zmodem behavior: overwrite
  files, crash recovery, etc.  Qodem does not expose these to the
  user; Qodem's Zmodem implementation will always use crash recovery
  or rename files to prevent overwrite when appropriate.

  Qodem always prompts for a filename for capture, screen dump, saved
  scrollback, and session log.  (Qmodem(tm) only prompts if the files
  do not already exist.)  Exception: if session log is specified on a
  phonebook entry toggle, qodem will not prompt for the filename but
  use the default session log filename specified in qodemrc.

  Qodem supports two kinds of DOORWAY mode: "Doorway FULL" and
  "Doorway MIXED".  "Doorway FULL" matches the behavior of
  Qmodem(tm)'s DOORWAY mode.  "Doorway MIXED" behaves like DOORWAY
  EXCEPT for a list of commands to honor.  These commands are stored
  in the qodemrc 'doorway_mixed_mode_commands' option.  "Doorway
  MIXED" allows one to use PgUp/PgDn and Alt-X (M-X) in Emacs yet
  still have ALT-PgUp/ALT-PgDn, scrollback, capture, etc.

  Qodem includes a Compose Key function (Alt-\) for entering a raw
  decimal byte value (0-255) or a 16-bit Unicode value (0-FFFF).

TERMINAL EMULATION LIMITATIONS

  The following features are not supported for VT10x: smooth
  scrolling, printing, keyboard locking, keyboard leds, and tests.

  132-column mode in VT100 is supported only within consoles/emulators
  that have 132 (or more) columns available.  For instance, 132-column
  VT100 output on a 128-column Linux console screen will result in
  incorrect behavior.

  VT52, VT10x, VT220, and LINUX numeric/application keypad modes do
  not work well.  This is due to Qodem's host console translating the
  numeric keypad keys on its own before sending the keystroke to the
  (n)curses library.  For example, the Linux console will transmit the
  code corresponding to KEY_END when the number pad "1 key" is pressed
  if NUMLOCK is off; if NUMLOCK is on the console will transmit a "1"
  when the "1 key" is pressed.  Qodem thus never actually sees the
  curses KEY_C1 code that would instruct Qodem to transmit the
  appropriate string to the host system.  The only key that appears to
  work right on most consoles is the number pad "5 key" (KEY_B2).

  VT52 HOLD SCREEN mode is not supported in any emulation (VT52,
  VT10x, LINUX).

  In VT52 graphics mode, the 3/, 5/, and 7/ characters (fraction
  numerators) are not rendered correctly.

  In addition to the VT100/VT102 limitations, the following features
  are not supported for VT220: user-defined keys (DECUDK),
  downloadable fonts (DECDLD), VT100/ANSI compatibility mode (DECSCL).
  (Also, because the VT220 emulation does not support DEC VT100/ANSI
  mode, it will fail the last part of the vttest "Test of VT52 mode".)
  The unsupported commands are parsed to keep a clean display, but not
  used otherwise.

  VT220 discards all data meant for the 'printer' (CSI Pc ? i).

  The ANSI.SYS screen mode switch sequence (ESC [ = Pn {h | l}) only
  supports enable/disable line wrap (Pn = 7); the various screen mode
  settings (e.g 40x25 mono, 640x480 16-color, etc.) are not supported.

DOCUMENTATION

  This README and the qodem man page are the primary documentation for
  qodem.

CONTRIBUTING

  Qodem is an open-source project under the GPL, meaning anyone is
  free to see and modify the source code and release their own
  versions.  However, we strongly encourage would-be developers to
  help out the official Qodem project rather than fork their own,
  since we believe more people will benefit that way.

  We won't keep out much, particularly code that helps portability,
  but please format your code to look similar to what's already here:
  tab stop 8, with tab characters, K&R-style braces and indentation.

ACKNOWLEDGMENTS

  We'd like to thank the following individuals:

      Paul Williams, for his excellent work documenting the DEC VT
      terminals at http://www.vt100.net/emu/dec_ansi_parser .

      Thomas E. Dickey, for his work on the XTerm emulator and the
      NCurses library.

      Both Mr. Williams and Mr. Dickey have answered numerous
      questions over the years in comp.terminals that were archived
      and greatly aided the development of Qodem's emulation layer.

      Miquel van Smoorenburg and the many developers involved in
      minicom who licensed their work under the GNU Public License.

      Martin Godisch for help in packaging and uploading to Debian.

SIGNIFICANT NEEDS

  TBD
