README for pbmtogf.
In the absence of proper documentation, this file will give you
essential information of pbmtogf.

WHAT IS PBMTOGF
===============

PBMTOGF is a little utility for converting a pbm file into a gf file
plus an accompanying pl file. In effect, it generates a font that can
be used by other typesetting systems, such as TeX, LaTeX.

A pbm file is a portable bitmap file. A gf file is a generic font file
which is the default output format of METAFONT. It contains
information of a bitmap font. A program gftopk can convert this file
into a pk file to be used by TeX, LaTeX and their driver programs such
as dvips to typeset documents. A pl file contains a font property
list. A program pltotf conterts this file into a tfm (TeX Font Matrix)
file to be used by TeX, LaTeX, etc.

The input to pbmtogf is a bitmap which contains one or more
pictures. Each picture will become a character in the generated
font. Currently, pbmtogf assumes the size of all pictures are the
same. The pictures are arranged in rows and columns. For example, a
bitmap of 300x200 pixels contains six pictures. The size of the
pictures are 100x100 pixel. They are arranged into rows of three.

Assuming this bitmap is store in a file named mymap.pbm, the following
command 
	pbmtogf -r2 -c3 mymap.pbm
will generate a font in the file mymap.600gf and mymap.pl. The font
name will be the basename of the input file, i.e., mymap in the aove
example, and the characters in the font will have codes starting from
0, i.e., the first character in the top row is character 0, the next
is character 1, and so on.

pbmtogf accepts the following command line options (with default value
in parentheses):
  -help  display this message
  -d     enable debugging
  -c<n>  n characters per row (1)
  -r<n>  n rows in the image  (1)
  -w<n>  character width in pixels  (width of bitmap)
  -h<n>  character height in pixels (height of bitmap)
  -f<n>  character code of first character
  -n<n>  number of characters  
  -s<n>  output resolution in pixels per inch (600)
  -z<n>  designe size in points     (12)

The following commands convert the gf and pl files to pk and tfm files
respectively:
	gftopk mymap.600gf
	pltotf mymap.tfm

After this conversion, you can use the font mymap in a TeX document
like this:

\font\myfont=mymap	%define and load the font
\myfont\char0		%use the first character in myfont
			%or better as below
			% to define a macro for the characters
\def\mychara{\myfont\char0}
			% use the macros in the text
This is a new character in parentheses (\mychara).

Or  you can use the font mymap in a LaTeX2e document like this:

\DeclareFontFamily{U}{mymap}{}
\DeclareFontShape{U}{mymap}{m}{n}{ <12> icons }{}
\DeclareFixedFont{\myfont}{U}{icons}{m}{n}{12pt}
\newcommand{\mychara}{\myfont\char0}
This is a new character in parentheses (\mychara).

INSTALLATION
============

After you unzip and untar the distribution, You should receive the
following files:

	  README   --- this file
	  COPYING  --- GNU public license
	  makefile
	  pbmtogf.h --- header files
	  gf.h
	  pbmtogf.c --- C source files
	  gf.c
	  pl.c
	  readpbm.c

To compile the program, you need make and a C compile. GNU make and
gcc are a good choice.  Type the command:
    make all
will compile the program and create an executable pbmtogf.

In the test subdirector, you will also receive a sample of pbm file
and the font files (gf, pl, tfm and pk) generated by pbmtogf. There is
a LaTeX file showing an example of using this font.

PORTABILITY
===========
Since pbmtogf does not use any system dependent functions, it should work
on many different platforms, though I only tested it in the following
systems:
	Red Hat Linux 4.1, 5.0, 5.1, 5.2
	SunOS 4.2
	Solaris
	Window95, Window NT with gnu-win32

AUTHOR
======

pbmtogf was written by Wai WONG (wwong@comp.hkbu.edu.hk).
The home page of pbmtogf can be found at
 http://www.comp.hkbu.edu.hk/~wwong/typeset/pbmtogf/index.html

19 July 1999