type1inst Release 3 (2 August 1996)

Introduction
------------

This is the README file for the type1inst utility.  type1inst makes it
easy for you to use Type 1 fonts that don't come with your
system with Ghostscript and/or X.  It also has preliminary support for
generating sample sheets for the fonts on your system.

type1inst is distributed under the terms of the GNU General Public
License (GPL).  See the file COPYING.  As such, you can use this
program free of charge.  Postcards, however, are welcome.


Warning
-------
 
1. THIS IS BETA SOFTWARE!  READ THE SECTION BELOW FOR THE PRGRAM'S
CURRENT LIMITATIONS!

Things You Need
---------------

There are some things you need in order to use type1inst.

- An installed and working copy of ghostscript.  Well, you at least
need the "pfbtops" utility which comes with gs which is used to put
the contents of some PostScript font files into a format more easily
digested by perl.

- The program itself is a perl script, so you will need a copy of perl
installed.  If your perl is installed somewhere else other than as
/usr/bin/perl you will need to edit the top line of the script to
specify exactly where your perl binary is located.  I am using version
5.001 of perl, however I doubt it's doing anything tricky that is in
version 5 so previous versions should work just as well.  I've been
constantly referring to the excellent "Learning Perl" book by Randal
Schwartz, which is based on version 4.

- Some Type 1 fonts you want to use (of course).  These should be in a
directory of their own.  These can be on a mounted
Windows/DOS/whatever partition - there is no need to make a copy of
them onto your UNIX partition.


Installing type1inst
--------------------

Just copy the script named "type1inst" which was spat out when you
unpacked the distribution into some convenient directory in your path.
You should probably put this README file somewhere safe too.


Using type1inst
---------------

There are two main things this program can do :

- Generate the "fonts.scale" file which X uses to pick up Type 1 fonts
which are in the current directory.  X will not do this for you.
Previously you may have had to write the file by hand (which is no
fun) but this program can automate that.

Unless you tell the script otherwise, this file will be created when
you run the script.  You can tell the script not to by using the
"-nox" command- line option.

- type1inst will also generate Fontmap files used by Ghostscript.
Since ghostscript has one system-wide Fontmap file you will then need
to add the contents of the generated Fontmap in the directory you run
the script to the main Fontmap and add the directory to the GS_LIB
environment variable (see note further down).  You can turn off
Fontmap generation by using the "-nogs" command-line switch.  DO NOT
USE THE ENVIRONMENT VARIABLE GS_FONTPATH!  This essentially does the
work that of this script when ghostscript starts up in constructing an
internal version of the Fontmap file.  If you have lots of fonts this
can mean it will take a long time for gs to start up.  The idea with
type1inst is that this work is only ever done once and when gs needs
to load a font it will find it in the generated Fontmap.

So, when you are using this program for the first time, or have just
updated the contents of a directory you need to :

1.  cd to the directory where your fonts are located.

2.  run type1inst.  This will generate the files "fonts.scale" and/or
"Fontmap" as described above (depending on which switches you use on
the commmand line).  Unless you use the "-silent" switch you will get
some numbers printed on the stdout which indicate how many fonts have
been successfully processed.  After all the fonts have been looked at
the script will print a final report on what happened and any errors
or problems that occurred.  If you choose to have fonts indexed for X
then "mkfontdir" will be run for you at the end and all you have to do
to use the fonts is either restart you X server, or if you are using
xfs, to restart it.  If you have not already done so, you will need to
tell either xfs or your server about the new font directory.  This
will be in their respective configuration files.  Read the manual
page.

NOTE: You will probably need to be root to make at least some of these
changes.


X Foundry Names
---------------

X font names include a string denoting the foundry where the
particular font came from.  Unfortunately, it seems that there is no
standard place this is stored in your average font file.  Many fonts
say something in the /Notice string near the top of the font file, and
indeed this is how the program attempts to determine where the current
font comes from.  For faces from large vendors like Adobe or Monotype
this works fine.  Most probably, however, you will have a font where
this fails.  type1inst will emit a message like :

-------------------------------------------------------
For 3 of these I couldn't figure out which foundry
the font is from.  Thus, these fonts will appear under the
foundry unknown, i.e. X font name -unknown-*.
Please consult the README file to see what this means.
-------------------------------------------------------

If you have got this far you are doing the right thing :-)

If you now look in the type1inst log file "type1inst.log", you will see
entries like :


brakeo_.pfb (BugRake-Oblique) : foundry not matched
  /Notice said : "BugRake was developed by Qaqaville Typography Inc."


The first word is the filename and in brackets the name of the font in that
file.  The /Notice string is then printed.  

More often than not, the /Notice string doesn't have anything useful in it.
This seems to be especially so with public domain fonts.  You'll just
have to live with it.  If, however, a number of your fonts have similar-
looking /Notice strings with a company or person's name, or something like
that then you might like to send a copy of one of the /Notice strings to
me and I'll add detection for your foundry into the next release.

As the message says, the foundry is set to "unknown", so if you can't see
them in "xfontsel", look there.

You can also override the foundry section of the X font name, as described
below.


Overriding Things
-----------------

Some fonts have internal font names which are a little verbose and as
described above, the script may not be able to determine which foundry
a particular font comes from.  An example of a verbose name is
"Courier10PitchBT-Roman" which was donated by Bitstream to the X
Consortium and comes with all X distributions.  Once you have a valid
"fonts.scale" file, you can then edit any part of the X font
specification to be anything you like and if you subsequently run the
script again it will use what is already in the file, so your changes
will be permanent.

The same goes for the Fontmap; if there is already an entry
corresponding to a particular filename, the program won't parse the
font again, it will just keep the old name.


Font Sample Sheets
------------------

type1inst also has the capability to produce sample sheet for your
fonts.  Just invoke the script with the "-samples" option.  A new
subdirectory called "samples" will be created, and in there for each
file will be a PostScript file which you can view/print with Ghostscript.
This is a somewhat nicer way to look at fonts than xfontsel.  A file 
called "allfonts.ps" is also created which has a line from each font.
Be warned, though, if you have lots of fonts the ghostscript will eat
memory at an alarming rate as it tries to load them all simultaneously.

When creating font sample pages, type1inst does not embed a copy of
the font in the file since this would use up a lot of unnecessary disk
space.  However, this means that the file will not print unless the
font in the sample is one of the standard 13 PostScript fonts.
Therefore, a simple script called t1embed is provided to embed the
required font into the specified document for printing.  Note this is
not necessary for viewing with Ghostscript, so long as the required
font is in the Fontmap.

An example : you have a file BugRake-Oblique stored as the file "brake.pfb"
in some directory.  Using the -samples option, a file is created called
"samples/BugRake-Oblique.ps" relative to the directory the font is in.
t1embed is not particurily smart (yet) and so cannot find the original font
if you run it in the "samples" directory.  Therefore, stay in the directory
where the actual outline file is kept and run 

   t1embed samples/BugRake-Oblique.ps

and you can then print it to a PostScript printer with

   lpr samples/BugRake-Oblique.ps

I consider the current font sample code to be less than perfect.  As you
will notice fonts with wide metrics (e.g. fixed width fonts like Courier)
go over the edge of the page.  The current program makes no attempt to
determine the metrics of the font and just prints the same strings for
each font whether they fit or not.  A future version will include a better
(and more complicated) method for generating samples which will involve
parsing an AFM file from Ghostscript to get the metrics and the width of
each line calculated to ensure it fits within the boundaries of the page.

Current Problems/Limitations
----------------------------

- The script won't yet work on anything which doesn't look like a UNIX since
it needs system commands like "mv", "rm" etc.  I'll get around to fixing
this eventually.

- The public domain Hershey fonts which are distributed with Ghostscript
don't look like normal PostScript fonts when actually reading the files.
They look more like PostScript code to make a new instance.  Thus, this
program skips over these.  

- Having _lots_ of fonts causes xfontsel's list of fonts to be about five
screens high :-(   [ not my fault ! ]

- Don't throw away all your bitmap fonts yet.  It seems there is more
than one way to write font names in X and some applications
(e.g. xmcd) can't match the fonts they want with anything this program
generates.  It looks like you can have less fields in the font
specification.  I really don't know much about this.  Perhaps we need to
generate aliases or something.

e.g.

slipperkicker(0):~# xmcd&
[1] 10958
slipperkicker(0):~# Warning: Cannot convert string "-*-helvetica-medium-r-*--10-100-*" to type FontStruct
Warning: Cannot convert string "-*-helvetica-medium-o-*--24-240-*" to type FontStruct
Warning: Cannot convert string "-*-helvetica-bold-o-*--14-140-*" to type FontStruct
Warning: Cannot convert string "-*-helvetica-bold-o-*--12-120-*" to type FontStruct
Warning: Cannot convert string "-*-helvetica-bold-r-*--12-120-*" to type FontStruct
Warning: Cannot convert string "-*-helvetica-*-o-*--14-140-*" to type FontStruct
Warning: Cannot convert string "-*-helvetica-medium-r-*--12-120-*" to type FontStruct
Warning: Cannot convert string "-*-times-bold-i-*--24-240-*" to type FontStruct
Warning: Cannot convert string "-*-times-bold-i-*--12-120-*" to type FontStruct


It would appear to be something to do with the 24-240 bit.  I can't
seem to select these in xfontsel (but this is a scalable font so you
should be able to get all sizes....????)


Thanks!
-------

My thanks go to the following people for submitting feedback :

- Andreas Dilger            <adilger@enel.ucalgary.ca>

    For the font sample code, many suggestions and some foundry names
as well.

- James A. Robinson         <jimr@simons-rock.edu>

    For foundry information on lots of public domain fonts.


Contacting the Author
---------------------

If you find a problem with this program or you would like to make a
suggestion, or whatever, feel free to e-mail me.  My address is

J.Macnicol@student.anu.edu.au

You should be able to pick up the latest version of this program from

http://goblet.anu.edu.au/~m9305357/type1inst.html



Good luck!



James Macnicol




