  BitFontEdit Manual
  David S.Lawyer  bf347@lafn.org
  v. 3.1.2 Aug. 1999 (3.1 is 1997)

  This software enables you to draw (create) your own bit-mapped font
  for VT220+ and most Wyse terminals (or other terminals which can emu-
  late them).  By doing some more C-programming, it could be extended to
  generate font for printers and X-terminals.  You draw the characters
  as *'s (pixels) in a text file using any editor or word processor.
  Then this program scans these drawings and converts them to the soft-
  font code needed for downloading to terminals.  You will likely need
  to do a small amount of "programming" in a terminal language to
  install your soft-font.  Another program converts soft-font to a draw-
  ing with *'s.  The extensive documentation includes the details of
  font languages (for terminals) and how to install soft-font on termi-
  nals.
  ______________________________________________________________________

  Table of Contents

  1. INTRODUCTION

     1.1 Contacting the Author
     1.2 Files
     1.3 What it Does
     1.4 What it Doesn't Do
     1.5 Unix-like Bias
     1.6 Soft-Font
     1.7 Difficulties You Will Face
     1.8 Future Improvements
        1.8.1 Terminals
        1.8.2 Printers
        1.8.3 You Can Help
     1.9 Does Your Terminal or Printer Support Soft-Font ?
     1.10 Terminal & Printer Lists (very incomplete)
        1.10.1 Terminal List (of some terminals that can download soft-fonts)
        1.10.2 Printer List (None Supported yet by BitFontEdit)

  2. GETTING & UTILIZING SOFT-FONT

     2.1 Finding Soft-Font
     2.2 Standard Character Sets
     2.3 Creating Soft-Font by Hand
     2.4 Six Steps to Create & Utilize Soft-Font
     2.5 Remapping the Keyboard
     2.6 7 or 8 Bit Codes and Font Banks

  3. DRAWING and INSTALLING THE CHARACTERS

     3.1 Introduction
     3.2 Pattern File Format
     3.3 Installing Soft-Font

  4. THE pat2sf PROGRAM

     4.1 Introduction
     4.2 Compiling pat2sf
     4.3 Running pat2sf
     4.4 Embedded Comments in Soft-Font

  5. CREATE A PATTERN FILE FROM SOFT-FONT: sf2pat

     5.1 Introduction
     5.2 Use to Translate Between Languages
     5.3 Can't Create Pattern File Exactly
     5.4 No Error Checking
     5.5 Running the Program

  ______________________________________________________________________

  1.  INTRODUCTION

  1.1.  Contacting the Author

  I would like to hear your comments and feedback.  Did you find this
  software useful?  To report bugs, let me know about your
  improvements/additions, correct my errors or suggest
  additions/improvements to the documentation contact me at
  bf347@lafn.org

  Be sure and  tell me the version number.  If your version is over a
  year old, make sure you're using the latest one before reporting
  problems.  The latest version might be posted at
  <ftp://metalab.unc.edu/pub/Linux/utils/terminal/>

  1.2.  Files

  o  C Source code etc.: scan.c, encode.c, pat2sf.h, (sf2pat.c),
     makefile

  o  Executable programs: pat2sf, sf2pat (get these by compiling)

  o  Documentation (may either be .txt or .html): index, BitFontEditMan
     (this file), font_langs C_code_notes install_softfont, history,
     other_font_tools, term_font_intro, copyright.  See below for more
     info on these files.

  o  Sample pattern files (Russian alphabet): 13rus_pat.txt,
     12rus_pat.txt

  The file which you draw your *-patterns in is called the "pattern
  file".  The main program, pat2sf, converts the PATtern file to Soft-
  Font.  The inverse program which converts soft-font to *-patterns is
  sf2pat.

  Here is a annotated list of the documents.  The .html files also have
  .txt versions.  Since the .html version may not be available on your
  system (or on the webpage you've viewing) the following links may be
  broken.

  o  BitFontEdit Manual <BitFontEditMan.html> is the manual for using
     BitFontEdit

  o  Terminal Font Introduction <term_font_intro.html> is a very brief
     introduction to fonts for terminals.

  o  History of BitFontEdit <history.html>

  o  Terminal Font Languages <font_langs.html> contain rules for
     encoding that the writer of this program needed to know about.

  o  Install Softfont <install_softfont.txt> describes how to install
     soft-font in terminal memory

  o  Other Font Tools <other_font_tools.txt> is a very incomplete
     description of software and documentation by others

  o  Overview of pat2sf Source Code <C_code_notes.html>

  o  This file: index.html

  o  Example pattern files: (Russian alphabet)  <13rus_pat.txt> and
     12rus_pat.txt.

  All of the above files should be found in a gzip (compressed) tar
  archive, (size 65k compressed).

  1.3.  What it Does

  This software is for designing (drawing) your own bit-mapped fonts
  (creating soft-font or downloadable font).  At present, it can only
  generate fonts for some text terminals (VT220, WYSE, or terminals that
  can emulate them).  If you don't know what a text terminal is (or want
  to find out how to configure them, see
  <http://metalab.unc.edu/LDP/HOWTO/Text-Terminal-HOWTO>.  In the future
  BitFontEdit may handle other "devices" such as printers.  To use it,
  you first create an ASCII "pattern" file containing drawings of your
  characters with *'s  representing pixels, using any editor or word
  processor.  Such a file has a required format.  Here is an example of
  a "band" of characters from a pattern file for the Russian alphabet.
  Char BO is the letter 'A', etc.:

   char B0  char B1  char B2  char B3  char B4  char B5  char B6  char B7
  |       ||       ||       ||       ||       ||       ||       ||       |
  |   *   ||****** ||****** ||*******||  *****||*******||*  *  *|| ***** |
  |  * *  ||*      ||*     *||*     *|| *    *||*      ||*  *  *||*     *|
  | *   * ||*      ||*     *||*      || *    *||*      || * * * ||      *|
  |*     *||*      ||*     *||*      || *    *||*      || * * * ||      *|
  |*     *||****** ||****** ||*      || *    *||*******|| ***** ||  **** |
  |*******||*     *||*     *||*      ||*     *||*      || * * * ||      *|
  |*     *||*     *||*     *||*      ||*     *||*      || * * * ||      *|
  |*     *||*     *||*     *||*      ||*     *||*      ||*  *  *||*     *|
  |*     *||*******||****** ||*      ||*******||*******||*  *  *|| ***** |
  |       ||       ||       ||       ||*     *||       ||       ||       |
  |       ||       ||       ||       ||       ||       ||       ||       |
  |       ||       ||       ||       ||       ||       ||       ||       |

  You then run my program on such a pattern file and obtain the soft-
  font code to download to a terminal or printer.  The font will then
  display on the terminal screen or print on a printer. You will proba-
  bly need to write a script file.

  Repeating the above paragraph in more detail:  You run the program
  (pat2sf) which scans the pattern file and converts the "drawings" into
  soft-font code.  Then you may want to manually edit (adding some
  commands to, etc.) the soft-font code.  Then after possibly sending
  some special commands to the device (printer or terminal) you send the
  soft-font to the device (you "download" it).  Then your new characters
  are now available to use at the printer or terminal.  But they are
  often lost when you turn off the power to the device because this
  erases the memory where the soft-font was stored.

  In order to conveniently do this soft-font download (mentioned above)
  you may need to write some kind of a script file to handle the
  download including setting up (configuring) your terminal for
  downloading and loading the font into the appropriate bank.

  1.4.  What it Doesn't Do

  It does not contain any fonts per se (except for a couple of examples
  of the Russian alphabet).  It creates only bit-mapped font and not
  scalable font.  It presently only works for mono-spaced font on dumb
  terminals and can't create proportional spaced font.  It seldom works
  to create font for terminal emulators on PC's, but will work if the
  emulation is 100% perfect.  Please let me know if you find an emulator
  that can use it.

  Since you may use any editor or word processor to "draw" the
  characters in an ASCII file, this "font editor" program doesn't
  actually do any editing.  But the final result is the same as a font
  editor since whatever editor you use gives you real soft-font as
  output after the program pat2sf scans your file.  In a sense this is a
  "font generator" since it converts one type of font format (your
  drawing) into another, but many so called "font generators" don't let
  you draw your own font so I no longer call this program a "font
  generator".

  1.5.  Unix-like Bias

  Most people who use text terminals run Unix-like operating systems.
  So while BitFontEdit may be used with almost any operating system, the
  terminology and examples are biased towards "Unix-like" systems
  (especially Linux).

  1.6.  Soft-Font

  Soft-font is computer code that is sent (downloaded) from a computer
  to a character device (a printer or terminal) to define the shape of
  certain characters (often an entire character set such as the Russian
  alphabet).  Once the soft-font for a character set is stored in the
  memory of the character device and selected, 7 or 8-bit ASCII
  character codes (or the like) sent to the device will result in
  display (or printing) of the character shapes specified by the
  previously loaded (and selected) soft-font.

  Soft-font may be purchased, written by hand (programming), or may be
  generated automatically by software such as this.  There are many
  languages used for soft-font and device control such as PCL6 (HP) and
  Esc/P2 (Epson) for printers; VT220, WYSE, and BDF (X-Windows) for
  terminals.  There are also languages for scalable fonts but you can't
  make scalable fonts with my software.

  Most modern terminals and many printers can download soft-font.  If
  there is any doubt  you had better make sure that your hardware can
  handle soft-font before spending time drawing characters.  At present,
  this software only works if your equipment can handle the following
  device control languages: Terminals: VT220, WYSE.  However, you are
  invited to write more code to cover other devices.

  1.7.  Difficulties You Will Face

  Creating a new font using this software is a lot of work and involves
  much more than just drawing the characters.  Hopefully, the font you
  create will be shared with others and you may want to incorporate it
  into some other program(s).  A major problem may be finding
  documentation for your terminal/printer.  Many people who have
  purchased one used find they have no manual.  Even if you have a
  manual, it may not provide the information you need.  For printers,
  you can usually readily find out what font language it supports such
  as PCL or ESP/P (various versions).

  For terminals, the situation is worse.  Even if you have a manual, it
  may be of no help unless you have a "Programmer's Manual".  Many user
  manuals don't even tell you if the terminal supports soft-font let
  alone other info you must know, such as the font languages supported
  and the character cell size for the pixel-characters.  Note that the
  cell sizes shown in most user manuals include space that is always
  left blank for separation of adjacent characters.  This size is thus
  larger (by how much?) than the size you need to know for creating your
  pattern file of pixels.

  Even if you are able to generate the softfont, you need to know the
  commands to send to download it to a certain bank and select it
  (activate) it for the display.  This documentation for some terminals
  is in the install_softfont file of BitFontEdit.

  It is also desirable to know (or learn) a scripting language such a a
  shell-script language.   If you think you're up to these tasks, please
  read on.  To do all of this requires that you know (or learn)
  something about very simple programming using printer (or terminal)
  control languages.  You may have trouble finding the documentation.
  It may not exist anywhere on the Internet (I've searched in vain for
  much of it) and even a search of all libraries in the US (or
  elsewhere) may fail to locate what you need.  Sometimes you may
  purchase the needed documentation.

  Since my software is usually supplied as C source code, you will
  likely need a C compiler to compile it.  Once compiled, the program
  will do most of the routine part of creating soft-font for you.
  Another task if you are creating a character set is to figure out how
  to map the keyboard to the characters, but how to do that is beyond
  the scope of this manual.  If you get as far as drawing a font for a
  character set, chances are you'll make a mistake in your drawings by
  inadvertently violating the format rules for it, resulting in error
  messages on your first try of running pat2sf.  With a little luck and
  effort you'll quickly correct your errors and finally succeed.

  1.8.  Future Improvements

  1.8.1.  Terminals

  This software only deals with terminals, but it is quite incomplete
  even for terminals.  The latest manuals for "dumb" terminals need to
  be checked as this software is based on pre-1990 manuals.  X window
  terminals need to be included.  More details are needed regarding the
  terminal control languages, emulations, and character-cell sizes for
  those who don't have (or can't find) their manuals.

  Thus far only two types of terminals  are covered: Wyse and VT220.
  These likely cover most of terminals which can download font since
  other brands of terminals tend to have Wyse or VT220 emulations.  X-
  window terminals use BDF format which is almost the same as Wyse
  except for the verbose "header" information required.

  1.8.2.  Printers

  This software could be extended to include printers.  For high
  resolution font, it is time consuming to draw (or type) the large
  number of pixels used.  You may be better off doing it using outline
  fonts (not supported by this software) except that as of mid 1997 I
  know of no freeware programs for this.   With outline fonts you don't
  need to type each pixel and it is easy to scale the font to various
  sizes.

  Extending this software to cover dot-matrix printers is a much larger
  task than that of creating this existing software for only 2 terminal
  categories.  This is so because there are many types of printer fonts:
  1.  There are proportional spaced fonts with various size cells within
  the same font.  2. There are compressed fonts (using very simple data
  compression methods) 3. There are complicated fonts created by a
  second pass of the print head where pixels may overlap each other.
  However, to just extend it to cover a simple printer font (not
  proportional spaced, etc.) would be relatively easy.

  1.8.3.  You Can Help

  I'm seeking help in the above projects.  If you can write the code for
  a few printers (including PCL and ESC/P formats) then you'll become
  the co-author of BitFontEdit.

  1.9.  Does Your Terminal or Printer Support Soft-Font ?

  Most modern printers and terminals do.  To find out if a terminal can
  do this, look at what may be called a "programmers manual/guide" for
  your terminal.  For printers (in most cases) one only needs to find
  out the emulation such as ESC/P 2 for Epson or PCL 5 for HP.
  Sometimes some useful information is in a "users manual/guide",  or
  even in a specification sheet.  In recent years, much of the technical
  information needed to program characters is not included in the
  printer or terminal manual provided to the purchaser.  Instead, it
  comes in an expensive "programmers manual" or the like.  For HP
  printers (and ones that can emulate them) there is a 1991 book called:
  "HP Laser-jet Programming" which includes programming soft-font.
  There are a number of other books for HP.

  1.10.  Terminal & Printer Lists (very incomplete)

  1.10.1.  Terminal List (of some terminals that can download soft-
  fonts)

  Needs updating.  ? => Uncertain LANGUAGES (VT220 or WYSE)

  o  Only VT220:        Qume QVT: 203, 321, 322, 323; DEC VT: 220, 320,
     330?, 340?, 420 Wyse: 185?, 520?

  o  Only WYSE:        Wyse: 60

  o  Both VT220 & WYSE: Qume QVT: 61, 62, 70, 191 Wyse: 99GT, 120, 150,
     160, 325, 370, MAX700?

     Can't download soft-fonts: CIT: 80, 101;  VT: 52, 100;  Wyse: 30,
     50; & many others.  This software will also work for some other
     models of terminals that have a Wyse(native) or VT220 emulation
     capability.  However, some terminals which claim to emulate a VT220
     can't accept user-created fonts.

  1.10.2.  Printer List (None Supported yet by BitFontEdit)

  LANGUAGES:  PCL6 (by HP), ESC/P2 (by Epson), IBM

  o  PCL6 (HP):  Most newer laser printers.

  o  ESC/P2:    Epson LQ series, Citizen GSX-240, CItoh ProWriter: C-610
     II & C-615 II, Brother: M4309A

  o  IBM:    IBM Proprinter,

  o  ESC/P2 & IBM: Pansonic 2123, 2124

  Can't download soft-fonts: Epson: RX, MX, & FX series

  2.  GETTING & UTILIZING SOFT-FONT

  2.1.  Finding Soft-Font

  If you have printers and/or terminals which accept soft-font and you
  need a font that's not available on your computer, how do you get it
  and install it?  You may possibly buy soft-font or find a shareware or
  freeware copy on the Internet.  But if the soft-font you need can't be
  readily located or costs too much, then you may want to create your
  own soft-font.  First you need to determine by looking over this
  document (and others) just what is involved.  This software may help
  you create (or generate) such soft-font code provided that the font is
  bit-mapped (can't be scaled).

  2.2.  Standard Character Sets

  Once you've decided to start the process of creating your own Soft-
  Font, then you need to zero in on just what characters you need and
  what their byte codes will be.  If you are creating a foreign language
  character set, you should strive to use a "standard" code chart to
  assign bytes to characters.  If you fail to do this you will not be
  able to exchange text files with others who do not use your system of
  encoding.

  Finding the "standard" code for a foreign alphabet (or for several
  alphabets supported by the same code chart) is often a difficult task
  since it may turn out that there is not just one "standard".  To your
  dismay, you may find out that the foreign alphabet codes used by
  various popular word processors and printers do not always adhere to
  ISO standards.  But there are sometimes certain defects in ISO
  standards.  You can find some information on foreign language codes
  and fonts on the Internet.  Usenet has the newsgroups comp.fonts and
  comp.std.internat.  A good search engine for the newsgroups is
  dejanews.com.  In 1990 there was a "Polygot" mailing list which was
  archived at ftp://tira.uchicago.edu but I can't find it there now.

  2.3.  Creating Soft-Font by Hand

  Using this BitFontEdit (or other <other_font_tools.txt> programs) is
  much faster than drawing the characters you want on graph paper and
  encoding them (creating soft-font) by hand.  But if you really want to
  understand how this software works (or spot check its results) then
  you may want to try writing the soft-font code by hand for a character
  or two.  In fact, if you only need to create a few characters for your
  printer or terminal and they are not too large (in terms of pixels),
  then it may be faster to create the soft-font entirely by hand.

  2.4.  Six Steps to Create & Utilize Soft-Font

  Six steps to create and utilize soft-font on a terminal are listed
  below.   Someone else may have already done some of these steps for
  you (and furnished you with the resulting software/files compatible
  with your computer, terminal, printer and operating system).  Thus you
  may not need to do all of these steps.

  1. Compile the C programs supplied to get "pat2sf" after possibly
     modifying the source code so it will work for your hardware.

  2. Draw bitmaps of your characters in a "pattern" file using any
     editor or word processor.

  3. Run the compiled font filter program (pat2sf) with a pattern file
     as input resulting in a soft-font file as output.

  4. Write a simple shell-script (= batch file) or other program to
     download the soft-font.  A sample shell-script is supplied for
     VT220..

  5. Figure out how to map the keyboard keys to the correct characters
     (including a "meta" key (or the like) to permit typing of up to 256
     8-bit characters).

  6. Determine the user interface to the character set(s).

  BitFontEdit provides steps 1, 3r and some help with step 4.  Step 1.
  can sometimes be done by just typing "make" if you have a compiler on
  your computer.  Step 2. can be done by anyone who can use an editor or
  word processor.  No help is provided here for solving step 6. but the
  next subsection provides a little help for solving step 5.

  2.5.  Remapping the Keyboard

  Some editors/word-processors can do this (for example the Emacs
  editor).  However, you will then get this mapping only when you use
  that editor/word processor.  Another way to re-map is to modify the
  operating system (the part sometimes called the "terminal driver").
  Most computers have programs available that will re-map the monitor
  keyboard, but it probably will not apply to dumb terminals.  At
  present, no such program exists for Linux.

  A naive person might think that all they need to do is arrange the
  pattern file in such a way that every character is assigned to the
  ASCII code which corresponds to the key on the keyboard they want to
  press for it.  This works fine to display characters as typed, but the
  characters you type are also stored in a file according to the
  encoding selected for the keyboard.  When you send such a file to
  someone else, they won't be able to make sense out of it unless they
  have the identical encoding scheme.

  A kludge to make the method of the above paragraph work is to
  translate every text file before you send it to anyone else, and also
  use the inverse translation for all files you get from outside.
  You'll probably have to write the translator for this yourself, but
  it's a fairly simple task.  This method probably only merits use as a
  last resort.

  2.6.  7 or 8 Bit Codes and Font Banks

  The conventional way to print a character on a printer (or display it
  on a terminal screen), is to send a byte to the device.  There are
  also 2-byte "Unicode" characters which form huge character set.  Some
  terminals (or terminal personalities or emulations) use only 7 bits
  out of the 8, resulting in up to 128 different characters (provided
  one includes control characters which normally don't display).  Other
  terminals allow both 8-bit and 7-bit characters permitting up to 256
  different characters if 8-bits are used.

  Some terminals have a number of user font banks inside the terminal.
  This means that you may download different sets of characters and then
  select the bank you wish to use.  With older Wyse terminals, you must
  use 2 banks to get an 8-bit character set since the capacity of one
  bank is not large enough to hold an 8-bit set.  For the case of 7-bit
  characters, you need to establish a method of switching font banks.  A
  special command that will execute a shell-script (= batch file) or
  short programs might do it.  An alias or shell function (on Unix-like
  systems) is another possibility.  For 8 bit character sets it will
  usually be necessary to establish a special shift key to get the
  keyboard to type the upper (or right bank) 128 characters (with the
  high order bit set to one).  This shift not only switches fonts but
  switches keyboard mapping.  In most cases you will want the special
  shift key to "lock" (or behave like a toggle) so that you don't need
  to hold it depressed while typing.

  In order to find out how all of this works with your devices you
  should look at the relevant manual for your printer or terminal.
  There may be a special manual which you need to buy or borrow.  Eight
  bit characters are the wave of the future.   (Some think it's
  Unicode.)  There are numerous eight bit character sets. Old terminals
  and printer are likely to have only 7-bit ASCII.  While a single byte
  defines a character it takes many (perhaps 20 or so) bytes (of soft-
  font) to define the bitmap shape of a character on a low resolution
  terminal or printer.  For letter quality printing several hundred
  bytes may be required per character.

  3.  DRAWING and INSTALLING THE CHARACTERS

  3.1.  Introduction

  To create your own fonts using BitFontEdit you must first "draw" the
  characters (see the "A" example below) in a pattern file using any
  convenient (and powerful) editor or word processor.

   ...*...
   ..*.*..        This is an example of a character (A) which you might
   .*...*.        "draw" in a pattern file.  It is really just a drawing of a
   *.....*        bitmap where the *'s might be ones and the dots zeros.  You
   *******        can draw this rapidly if you start out with "blank" cells
   *.....*        of all dots.  Your editor or word processor may permit you
   *.....*        to define "macros", "abbreviations" or "keyboard scripts"
   *.....*        so that just pressing a key will draw a short row or
   *.....*        column of *'s.  Another key may be programmed to replace
   *.....*        a dot with a * (and conversely).  The * symbol is known
   .......        as an "on" pixel, while the dots represent blank pixels.
   .......

  Note that the appearance of the A when displayed or printed on a
  device will not be as narrow as the A shown above since the *'s on a
  vertical line may be about as close together as the *'s on a
  horizontal line when the character prints or displays.  This pattern
  may be called a "dot-matrix" or a "character-matrix".  The "dots" in
  this dot-matrix are represented by *'s (and not by the dots used for
  the background).  Since  a "glyph" is the shape of a character, the
  character-matrix is also a "glyph".

  As an alternative format, you may use blanks for the background
  instead of dots and then use vertical bars | to separate characters
  (instead of white space).  BitFontEdit  will sense which format your
  are using and behave accordingly.  Which method should you use?  For
  small font, a blank background looks better but the dots show where *
  pixels could be placed for a larger font.  A pattern file must use
  only one of these two methods (Don't mix methods.).

  3.2.  Pattern File Format

  You should first look at an actual pattern file.  It might use the
  suffix (extension) .pat.  A pattern file is a "drawing" of many
  characters such as the large A (a dot-matrix or bitmap character)
  shown previously.  The file begins with optional comment lines, each
  starting with #.  The next two lines are file-header lines for the
  entire file. The first file_header line must contain three ASCII
  integers in this order: 1. cell width (in pixels)  2. cell height (in
  pixels) 3. number of character matrices per row (often 8 or less).
  Any non-digit characters or words are permitted between these
  characters.  Example: Cell width = 7 cells.  Cell height = 12.  8
  chars/band.

  The cell size is the size of a rectangular pattern in the pattern
  file.  Index origin is 1 when communicating with the user but is 0 in
  most of the source code since arrays in the C language have index
  origin = 0.  Don't confuse cell sizes used for this program with the
  larger cell sizes shown in most manuals which include regions where
  *-pixels are normally not permitted.  Such "forbidden" regions enforce
  the separation of adjacent characters on the CRT.

  The second line should be an important comment which should identify
  the font, its author, the date, etc.  Both of these header lines will
  be displayed on the CRT each time you generate soft-font.  These 2
  lines are also automatically put at the end of the soft-font file if
  it will not foul up the downloading of it.

  Next after the above mentioned two header lines in the pattern file
  are thick-rows of dot-matrix characters (with *-pixels).  Each such
  thick-row is called a "band" and will contain perhaps 8 characters for
  small size dot-matrices.  The exact number of characters/band (could
  be 8) is specified in the first comment line the C program.  The last
  band may contain a smaller number of characters.

  Every band starts with a band-header line.  These band header lines
  should contain the character numbers etc. but may contain anything (or
  even be a blank line).  When blank pixels are represented by dots,
  each dot-matrix character is separated from the adjacent one to its
  right (or left) by one or more vertical "columns" of white space.
  When the background (= blank pixels) is represented by spaces (blank),
  vertical bars: | are used (no white space allowed except for the
  spaces within a character matrix).  At present you need two vertical
  bars: || separating adjacent characters a single vertical bar before
  the first character and after the last character in a band.

  3.3.  Installing Soft-Font

  To get soft-font you must run the font generator program (pat2sf) on
  the pattern file.  See ``Running pat2sf.''  This will create a soft-
  font file ready to download.  In some cases all you need to do then is
  to copy this soft-font file to the printer or terminal and your new
  font is installed.  In most cases however, there are other things to
  do in order to install the soft-font such as setting up the printer or
  terminal in an appropriate way and assigning the new font to a certain
  font bank.  There are various ways of doing this.  One is to edit the
  soft-font file and add the additional codes.  In other cases you may
  decide to to write a shell script (= batch file) to install the font,
  one line of which will copy the soft-font file contents to the printer
  or terminal.  Some examples for terminals may be found in
  install_softfont. <install_softfont.txt>

  For loading just a few characters you may want to put the soft-font
  directly into the shell-script (= batch file) which is used to install
  them.  In this case (in DOS or Unix-like systems) you may "echo" the
  soft-font to the terminal or printer using the > for redirection.

  If you want to understand how the patterns (= glyphs) are encoded into
  soft-font you should study either certain printer or terminal manuals.
  If you don't have a manual, see the font_langs <font_langs.html>
  document.   However, there are often prefix (header) and suffix
  (trailer) codes that need to be added to the encoding of the patterns,
  some examples of which will be found in install_softfont.
  <install_softfont.txt>.  It's often feasible to put the header and
  trailer for the entire soft-font code into a shell-script (Unix-like)
  or batch file (PC).  If each character encoding needs a header and/or
  trailer, it should be added automatically by BitFontEdit's  pat2sf.

  4.  THE pat2sf PROGRAM

  4.1.  Introduction

  There are various "languages" used by printers and terminals
  (devices).  Soft-font is written in these languages.  Examples for
  printers are Esc/P2 for Epson Printers (and compatibles) and PCL6 for
  HP Printers (and compatibles).  Examples for terminals are WYSE and
  VT220.  Each language has it own method of encoding.  My program to
  create soft-fonts in various device languages (not C of course) is
  written in the C language.  If this software doesn't work for your
  situation you may need to modify my C program.

  pat2sf operates on the pattern file in two stages.  The first stage
  scans the file and puts the *'s (pixels) of the file into matrices in
  the computer's memory.  This is done by the code in source file
  scan.c.  The second stage is to read these matrices and encode the *'s
  of the matrices into soft-font (using the the appropriate language
  such as PCL).  This is done by functions in the file: encode.c which
  are called from scan.c.  For adding a new language, one must edit
  encode.c and add new functions etc. for the new language.  pat2sf.h is
  a header file for defining data types and constants common to both *.c
  files.  For a more detailed description of the code I've written, see
  both the the file C-code_notes <C_code_notes.html> and the source code
  files.  Also see font_langs <font_langs.html> for the rules to use for
  transforming bit-maps into soft-font code.

  4.2.  Compiling pat2sf

  If you need to use pat2sf (main program of BitFontEdit) to create
  soft-font, you may need to compile the C source code for it.  A Unix-
  style "makefile" is supplied so in some cases all you need to do is to
  type "make" at the command line prompt to compile it.  You may want to
  look at the makefile and change the options given to the compiler.

  You may need to modify the C programs a little before compiling.  At
  the start of pat2sf.h it #defines the maximum character cell size (in
  Pixels).  It also #defines the maximum number of character-matrices (
  = patterns) per band in the input file.  These 3 #defines determine
  array sizes in the program.  When most compliers handle dynamic
  arrays, the C code will be modified so that these #defines will no
  longer be needed.  Also #defined is the line length of your input file
  (I made it 80).

  4.3.  Running pat2sf

  When running the program pat2sf to generate a soft-font file you must
  specify the type of font (the font language) you wish to generate.
  Don't neglect to determine what LANG_OPTIONS you need.  Typing pat2sf
  alone on the command line displays something like:

  --------------------------------To get soft-
  font:------------------------------- pat2sf  [OPTIONS]  lang
  [LANG_OPTIONS]  pattern_file  >  softfont_file lang:  the soft-font
  language.  E.g. vt for vt220 terminals.  Consult help.  pattern_file:
  the name of the file in which you drew your Characters.
  softfont_file: the name of the file which this program will create.
  OPTIONS:                (Don't use "=" for arguments to letter
  options.)  -p   --pad_level=80   Append 80 etc. (default=0) padding
  nulls to each line of output.  -s   --stdin      use standard input.
  LANG_OPTIONS:  Depends on language.  See help below to show them.
  -----------------------------------To get
  help:--------------------------------- pat2sf -v   --version    shows
  version number.  pat2sf                  Display this message pat2sf
  --help list    Show list of supported Languages (LANG).  pat2sf --help
  LANG    Show LANG_OPTIONS for Language LANG in this message.  NOTE:
  You must read the manual to find out format of pattern_file, etc.

  Then after you have "drawn" your font in a pattern file (or gotten a
  pattern file from someone else), execute the font generation program
  (pat2sf).  As the program runs, watch the screen closely and make sure
  that the messages which appear on the screen are OK and that the
  reported cell size is correct, etc.

  The header lines from your pattern file should appear on the CRT.  If
  they don't something is wrong.  The only time you should see pixel
  lines from your pattern file on the screen is when an error message is
  being displayed.  If your header lines are the full width of the
  screen and your terminal has autowrap enabled, it may appear that the
  header lines shown on the screen are double spaced (blank lines
  display between the header lines).  This is nothing to be concerned
  about.

  You now (hopefully) have created a soft-font file ready to download.
  You may want to inspect it before downloading it to see if it looks
  reasonable.  Ditto if it doesn't work right.  You may do this using
  any editor or word processor provided that it can handle control
  characters (or binary for the case of printer font).  VT220 soft-font
  could even contain a couple of meta-characters (above char. no. 127)
  if they have been manually added to mark the start and end of
  downloading.  You could even verify the code for a certain character
  manually using the coding principles shown in your terminal manual, or
  font_langs <font_langs.html>, etc.  For dumb terminal fonts, at the
  end of the soft-font file you should find certain comments about the
  font including the 2 main header lines taken from the pattern file.
  These are comments embedded in the soft-font.

  4.4.  Embedded Comments in Soft-Font

  It is sometimes feasible to embed comments in the soft-font even
  though font languages don't support comments.  The purpose of such is
  to enable one to use an editor (perhaps an editor in binary mode) to
  examine the soft-font file to determine what the font is for, dates,
  authors, etc.  For dumb terminals, pat2sf simply adds these comments
  at the end of the soft-font code.  These comments are thus also
  "downloaded" to the terminal after the font is downloaded.  Since a
  terminal doesn't know that they are comments, they may be displayed.
  It's unlikely that this will cause any damage to the font you've just
  downloaded.  No decision has been made yet as to how to do this for
  printers since it would both waste paper and be confusing for the
  printer to print out the comments after each font download.  There may
  be ways to embed comments within commands that do nothing of any
  significance.

  5.  CREATE A PATTERN FILE FROM SOFT-FONT: sf2pat

  5.1.  Introduction

  The sf2pat program converts soft-font for Wyse or VT220 terminals to a
  drawing of a bitmap (a pattern file).  This bitmap pattern file is
  just an ordinary ASCII file with pixels dots represented by *'s.  The
  file may then be edited and converted back into soft-font using my
  pat2sf program.  This permits one to edit existing soft-fonts.  sf2pat
  means Soft-Font to PATtern.  This program, sf2pat does the inverse of
  pat2sf.

  In order to fully understand the sf2pat program, you should first
  understand the pat2sf program (as described elsewhere in this
  document).  This is because sf2pat is just the inverse of pat2sf.
  Note that using this software creates a pattern file conforming to the
  format per this document (with a background of spaces).

  5.2.  Use to Translate Between Languages

  One may attempt to use these two programs to translate soft-font from
  one language to another.  For example one could start with soft-font
  for a Wyse terminal and then run sf2pat -W on it.  The resulting
  pattern file (after adding the cell size and chars/band size using an
  editor) is then given as input to he pat2sf program and VT220 type
  soft-font is created.  You have just translated (by a 2-step process)
  Wyse font to VT220 font.  Of course this is bit-mapped font and both
  fonts will have identical pixels.

  If the original soft-font is higher or wider (in pixels) than is
  permitted by the target font, then it may not work.  Pixels that wind
  up outside the allowed boundaries are either missing from the target
  font or (even worse) they may be automatically extended and create
  other new (and erroneous) pixels.  For example, for VT220 any pixel in
  the 8th column will automatically create a couple more pixels to the
  right of it.  You might be able to work around this with a lot of
  editing work.

  Another possible problem is that the translated font may not be of the
  same physical size if the dots/inch resolutions of the terminals are
  different and thus may not look right.

  5.3.  Can't Create Pattern File Exactly

  A file of soft-font contains the shape of the characters, but it lacks
  certain information required to create a complete pattern file per my
  format.  You can supply some of the missing information on the command
  line when you run sf2pat.  Other information you'll need to add
  manually to the pattern file using any convenient editor or word
  processor.

  Since soft-font supplied by others is not likely to contain comments
  such as the number of dot-matrix characters per "band" (= thick row on
  a sheet of printout), some information from the original pattern file
  (or the like) will be lost.  Most soft-font does not tell one what
  type of separators were used to separate characters in a pattern file,
  nor what the comment and band header lines said.  Also, there may have
  been no pattern file if the font was created by hand or by someone
  else's software.  Until someone makes this program clairvoyant you
  will need to add some of this information to the pattern file using an
  editor.

  5.4.  No Error Checking

  While the font generator program (pat2sf) does much error checking on
  the pattern file to see if it is in the correct format the sf2pat
  program does little error checking of the soft-font code.  It assumes
  that you have a soft-font code that works OK.  But even if it works OK
  its format may not be exactly correct.  Thus you may need to do some
  editing of the soft-font file before running this program (or after
  this program fails).

  5.5.  Running the Program

  Type sf2pat to see what the options are.  You must either use the -W
  (Wyse) of -V (VT220) option.  The -p option is useful to send the
  output pattern file to the screen so you can preview what your output
  file will look like.  To do this use the -p option and don't redirect
  the output to a file (Don't use >).  You should see the large
  character matrices (*-patterns) on the screen.  If you don't,
  something is wrong.

  Also, you should give the height or width of the character cells, but
  if you don't know them, you will still get default results.  In case
  of such default, the character cells will likely be too large for the
  characters.  By inspecting the pattern file you may be able to guess
  what the cell size should be and then rerun pat2sf using that size.
  Note that you only give the width for Wyse and you only give the
  height for VT220.

  Usage: sf2pat [options]  [soft-font_file]  > pattern_file Options: -V
  font is for a VT220 type terminal.  -W  font is for a Wyse type
  terminal.  -s  use Standard input.  -p  Preview pattern output on CRT
  (no messages shown).  -h 16  Only for VT220.  Char-cell Height=16.
  Default is up to 5 too high.  -w  7  Only for Wyse.  Char-cell Width
  is 7.  Default = 8.  -b  6  chars/Band = 6. (Put 6 dot-matrix chars
  per line).  Default = 8.

