Qodem Getting Started Guide

Qodem strives to be faithful to the DOS-based Qmodem, however computers have changed significantly since the days of DOS. This guide is meant to help make a new user's experience with Qodem better.

Getting Qodem to work well on a stock Linux or Mac installation involves checking several things:

Screen - Qodem needs at least 80 columns by 25 rows and white text on black background.
Font - Qodem needs a Unicode font that includes both the CP437 glyphs and the DEC multinational character sets.
Keyboard - Qodem uses several function keys that modern environments often co-opt for other functions. Qodem will respond to other keystrokes if the function keys are unavailable. Also, Qodem needs the Alt or Meta key to send a separate escape character, NOT set the 8th bit.
Locale - Qodem needs both a Unicode locale and a non-Unicode locale to use when spawning shells and connecting to other Unix-like systems.
Other Qodem options - the Qodem options file may need to be edited further for a specific environment.

These items each have their own detailed sections below. Most of these things are due to how distributions set up their terminals differently from the raw Linux console. And the end is a section describing the setup I use.

But assuming that everything is set up well, how should Qodem work on its first run? That is the subject of the next section.

First Run

When Qodem runs for the first time, it will do several things:

It will create several directories. On Unix-like systems, these are ~/.qodem, ~/.qodem/scripts, ~/qodem, and ~/qodem/host; on Windows, these are My Documents\qodem\prefs, My Documents\qodem\host, and My Documents\qodem\script. These directories are used to store configuration files, user-generated and Quicklearn-generated scripts, downloaded files, and host mode messages and files.
On Unix-like systems, it will also create a FIFO (named pipe file) at ~/.qodem/scripts/script.stderr. This file is used to route a script's stderr stream to the display.
Qodem will populate ~/.qodem with several files, including the Qodem options file (~/.qodem/qodemrc or My Documents\qodem\prefs\qodemrc.txt). The options file is a plain text file and can be edited by hand or by typing Alt-N in terminal mode. Blank lines and lines beginning with '#' are ignored. Every option has a description and a default value. If the options file is deleted, it will be re-created with defaults the next time Qodem runs.

Qodem will start in the phonebook screen:
Phonebook Initial
Image

The bottom line shows the status line. This line updates through most of the Qodem screens to provide hints on which actions are available.

Qodem populates its first phonebook with an entry for the local system, several bulletin boards, and some other terminal systems. From this point you can navigate to an entry and press Enter to connect.

Adding a new system to the phonebook is straightforward: press the Insert key or 'I' to see the new/revise entry screen:
Phonebook New Entry Image

Use the arrow keys to navigate between fields, the status line will update with each field. Some fields require selecting from a list, press F2 or the space bar to bring up the list and F10 or Enter to select the option. For this example, use the LOCAL method and X_UTF8 emulation:
Phonebook Entry Filled In Image

After you have gotten the entry set up, press F10 or Alt-Enter to save the entry:
Phonebook Saved Entry Image

Press Enter again to dial the entry and it will switch to terminal mode:
TERMINAL Mode Image

In terminal mode most keystrokes are passed to the remote system (in this case, the spawned shell). Pressing Alt-Z brings up a menu of other keystrokes:
TERMINAL Mode Menu Image

When ready to exit Qodem, press Alt-X while in terminal mode (or Ctrl-C if Qodem is offline) to bring up the exit dialog:
Exit Dialog Image

When you are ready to explore more BBS systems, press 'L' in the phonebook and use arrow keys to select the Telnet BBS Guide list of systems:
Phonebook Load File Dialog Image

Press Enter to load the list:
Phonebook Telnet BBS Guide Fonebook Image

Now go telnet away and enjoy!

Colors

Screen

Font

Qodem requires a Unicode font that includes glyphs from the CP437 and DEC multinational character sets. Some good fonts to use are:

Terminus. Some VT100 line-drawing characters may be missing, but CP437 coverage is very good.
uni_vga. This is the default Linux console font (what one gets from executing 'setfont' with no arguments). You can download uni_vga including a version converted to TrueType at this link.
Unifont. Generally looks OK, but some of the VT100 line-drawing characters are not very pretty.
The default font on Mac OSX Terminal.app.

Unfortunately, no single font solves the issue best. The only font that seems to have every needed glyph and looks very good is uni_vga, however uni_vga can be small-and-sharp or larger-and-blurry on modern displays. The second best is Terminus: it looks very good and is only missing a handful of VT100 graphics glyphs that are very rarely used.

Keyboard

Qodem needs the keyboard to send the ESCape character for the Alt/Meta key. Many X11 terminals are configured for the Alt/Meta key to set the 8th bit by default and will need to be changed. Several options are available:

Configure the terminal through its menu interface to send the ESCape key. On Mac Terminal.app look for the option labeled "Use option as meta key" in "Preferences → Settings → Keyboard" (Leopard 10.5 / Snow Leopard 10.6) or "Window Settings → Keyboard" (Tiger 10.4).

Use uxterm, and add these lines to ~/.Xresources:


XTerm*eightBitInput:     true
XTerm*metaSendsEscape:   true
UXTerm*eightBitInput:    true
UXTerm*metaSendsEscape:  true

You can verify that the Alt/Meta key is sending ESCape by running 'cat' in the shell and typing Alt-X, you should see multiple characters (typically ^[x, maybe ←x) instead of one.

Locale

Locales are a complex issue for Qodem:

The locale of the terminal/console that Qodem uses to display glyphs to the user at the keyboard MUST be UTF-8. If it isn't, Qodem will look very ugly and might not handle keyboard input correctly either.
When Qodem connects to remote systems, the code page of those systems depends on the terminal emulation:
- TTY, DEBUG, ANSI, Avatar, LINUX, and XTERM emulations use 8 bit characters and can have different code pages for the high-bit characters. Qodem currently supports many DOS and Windows codepages including CP437, CP850, KOI8-R/U, Windows 1250/1251/1252, ISO-8859-1, and more.
- VT52, VT100, and VT102 emulations are defined by their standards to be 7-bit only, so only ASCII characters and DEC Special Graphics characters will be seen.
- VT220 emulation uses 8-bit characters but has multiple defined code pages for the high-bit characters (DEC multinational characters).
- L_UTF8 and X_UTF8 use UTF-8 encoded characters throughout.
- ATASCII and PETSCII have custom 8-bit encodings that are not quite ASCII. PETSCII in particular also needs the C64 Pro Mono font from Style.
When the remote system is a Unix-like system, the LANG environment variable must be set correctly to get the remote system to send either 8-bit characters or UTF-8 encoded characters.

Much of this complexity arises due to Qodem's niche: it lives between DOS and Unix-like systems, and uses ncurses for output and gettext for translation. Getting it right from scratch can be a challenge, but fortunately the various distributions have made this much easier.

The most straightforward way to handle locales is:

Ensure you are running a UTF-8 locale by checking the LANG environment variable in your shell. It should have "UTF-8" in the value somewhere, e.g. "en_US.UTF-8" .
Edit qodemrc (or qodemrc.txt) and ensure that the value for utf8_lang matches your LANG environment variable value.
qodemrc also has a iso8859_lang value that defaults to "C" (no translation). You can put another value here as long as it does NOT contain UTF-8, e.g. "en_US". If you get warnings about 'setlocale' then either leave it as "C" or try to add the locale to your system. On Debian, you can run 'dpkg-reconfigure locales' to add support for an 8-bit locale.

My Setup

Right now I run Qodem on Debian with the following packages installed: xfonts-terminus, xfonts-terminus-dos, and xterm.

When I am in X11 I just launch xqodem, which runs Qodem in a uxterm at 80x25. But when I want a general uxterm for command line work, I launch uxterm using this shell script:

#!/bin/bash

# uni_vga font
# This font has complete coverage of every glyph and looks great, but
# it is a bit small on large displays.  160x80 on a 1280x800 display.
# exec uxterm -fn -bolkhov-vga-medium-r-normal--16-160-75-75-c-80-iso10646-1

# Terminus font
# This font is small but can cram close to 160x80 on a 1280x800
# display.  It is only missing one unusual VT100 special graphics
# glyph.
# exec uxterm -fn -xos4-terminus-medium-r-normal--16-160-72-72-c-80-iso10646-1 -fg white -bg black

# Terminus font
# This font is very nice sized on my 17'' 1280x1024 display at 128x40
# characters.  It is only missing a couple of VT100 line drawing
# glyphs.
exec uxterm -fn -xos4-terminus-medium-r-normal--20-200-72-72-c-100-iso10646-1 -fg white -bg black

My ~/.Xresources looks like this:

! XTerm configuration to reproduce DOS colors.
! Credits to Emil Mikulic at http://dmr.ath.cx/notes/xterm.html
xterm*foreground: rgb:a8/a8/a8
xterm*background: rgb:00/00/00
xterm*color0: rgb:00/00/00
xterm*color1: rgb:a8/00/00
xterm*color2: rgb:00/a8/00
xterm*color3: rgb:a8/54/00
xterm*color4: rgb:00/00/a8
xterm*color5: rgb:a8/00/a8
xterm*color6: rgb:00/a8/a8
xterm*color7: rgb:a8/a8/a8
xterm*color8: rgb:54/54/54
xterm*color9: rgb:fc/54/54
xterm*color10: rgb:54/fc/54
xterm*color11: rgb:fc/fc/54
xterm*color12: rgb:54/54/fc
xterm*color13: rgb:fc/54/fc
xterm*color14: rgb:54/fc/fc
xterm*color15: rgb:fc/fc/fc
xterm*boldMode: false
xterm*boldColors: true
xterm*colorBDMode: true
xterm*colorBD: rgb:fc/fc/fc

I ran 'dpkg-reconfigure locales' and selected both 'en_US.UTF-8' and 'en_US' . My LANG environment variable is set to 'en_US.UTF-8'. My ~/.qodem/qodemrc has utf8_lang = en_US.UTF-8 and iso8859_lang = C.