type1inst Version 0.6 (20 June 1997)

                         Author : James Macnicol

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 basic support for generating font
sample sheets for the Type 1 fonts on your system.

Note : If you are using a commercial UNIX which comes with Adobe's
Display PostScript (DPS) system you do not need type1inst.  The
makepsres utility does what you want (with output albeit in a very
different form).  Read the manual page for more details.

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 but there is no warranty.

type1inst lives on the Linux archive sunsite.unc.edu in
/pub/Linux/X11/xutils.  Updates will be placed there as required.


Warnings
--------
 
1. THIS IS BETA SOFTWARE!  READ THE SECTION BELOW WHICH DETAILS THE
PROGRAM'S CURRENT LIMITATIONS!

2. This is a long document!

Quick Start for RedHat Linux Users
----------------------------------

Elliot Lee from RedHat has kindly contributed a script called `xgentype1dir'
which simplifies the use of type1inst on RedHat systems.  Simply copy (or
symlink) your new fonts into the standard directory where RedHat puts
Type 1 fonts (the directory $TOPXDIR/lib/fonts/Type1) and run the script.
When you re-start your X server the fonts should be available.  If not you
will need to read on.....

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

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

- An installed and working copy of GNU groff.  Well, you at least need
the "pfbtops" utility which comes with groff that is used to put the
contents of binary PostScript font files (ones with names that end in
.pfb) into a textual format more easily used.

- 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 scripts to
specify exactly where your perl binary is located.  I am using version
5.003 of perl, however I doubt it's doing anything tricky that is in
version 5 so previous versions should work just as well.  Besides,
everything I know about the language has comes from the excellent
"Learning Perl" book by Randal Schwartz, which is based on version 4
of Perl.

- Some Type 1 fonts you want to use (of course).  These can be located
anywhere you like and can be distributed over a number of directories
if you want.  NOTE : since X calls its font index file "fonts.scale",
you will not be able to use fonts which are on a DOS filesystem
(because of the stupid 8.3 file naming in the old DOS fs).  It does
work from a Windows 95 VFAT partition, though.

- type1inst generates files for use with the X Window System and/or
Ghostscript so you will want one or the other or both of these
installed.


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

Just copy the scripts named "type1inst" and "t1embed", which were
created when you unpacked the distribution, into some convenient
directory in your PATH (e.g. /usr/local/bin).  You should probably put
this README file somewhere safe in case you want to refer to it later.
A manual page is now also provided which sumarizes the options the
script takes (but is not really a subtitute for this document).  Just
copy "type1inst.man" into the appropriate directory, e.g.

cp type1inst.man /usr/local/man/man1/type1inst.1

(assuming, of course, that you have permission to write there).


What type1inst can do
---------------------

There are three main things this program can do :

1. Generate the "fonts.scale" file which X uses to pick up Type 1 fonts
which are in the current directory.  X will not create this file for
you.  Previously you had to write the file by hand (which is no fun)
but this program automates that process by extracting as much relevant
information as it can from the font files themselves.

2. type1inst can also generate entries for fonts which you can insert
into Ghostscript's "Fontmap" configuration file.  See the Ghostscript
documentation for more info.  This is used mainly to speed up
Ghostscript's starting time, since it will go out and manually
construct its own version of this information each time you run it if
the Fontmap doesn't contain entries for all the fonts you want to use.
This can take a long time if you have a lot of fonts.  Using type1inst
ensures this is only ever done once.

3. You can also make font sample sheets which lay out some text on a
page so you can see what a particular font looks like (similar, but
not as fancy as the ones produced by version 4 of the Adobe Type
Manager for Windows and Macintosh).


By default, the program does items 1 and 2 above.  If you want font
sample sheets generated, use the -samples command-line switch.  If,
for some reason, you want to suppress the generation of either
"fonts.scale" or "Fontmap", you can use the "-nox" or "-nogs" switches
respectively.  All messages can be suppressed with the "-silent"
switch if you don't want to see them.


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

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

To install your fonts in X and/or Ghostscript you need to do the
following steps for each directory in which you have fonts you want to
use.

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.  If you want font sample sheets, don't forget to
include the "-samples" switch when you run it.  If this is the first
time you have ever run the program and there are a lot of fonts then
this can take some time.  On the standard output is first printed a
count of the total number of fonts in the directory then a count is
printed of the number processed so far.

3. If you are setting up fonts for X :

A file called "fonts.scale" has been generated by type1inst which has
then run the "mkfontdir" program to make a "fonts.dir" file (possibly
adding information about any bitmap fonts you may have in the
directory as well).  This file contains all the information your X
server needs in order to use the fonts.  If this is the first time you
have used this directory, you now need to tell your X server where it
is so that it can use the fonts.  How you do this depends on the
mechanism by which the X server gets its fonts.

In most cases your X server handles fonts itself, i.e. in the X server
configuration there is information about which directories contain
fonts which it can use.  How this is done varies from implementation
to implementation.  If you are using the popular XFree86 package for
PC UNIXes there is a file called "XF86Config" which has a section
called "FontPath" that list all the directories in which the X server
should look for fonts when it starts up.  Add an entry in FontPath for
your new directory and then restart the X server.  The fonts should
now be available.  For other X implementations, consult your
documentation on how to add directories to your X font path.

The second (less common) way for the X server to obtain fonts is via
an X font server, i.e. a machine running the program xfs.  Note that
xfs and the X server can be running on the same machine or on
different machines over a network.  Similar to the previous case of
the X server which handles its own fonts, you also need to tell xfs
where the new fonts are.  The font path for xfs is listed in the
"catalogue" section of its configuration file and this is where you
need to add a new entry.  See the xfs(1) manual page for details.
Once you have done this restart xfs and then the new fonts should be
available to all X servers which get their fonts from the font server.

If you are updating a directory you have used previously you need only
restart your X server or xfs to make the changes effective.

4.  If you are setting up fonts for use with Ghostscript :

A file called "Fontmap" has been generated by type1inst in the current
directory.  Since Ghostscript has one global Fontmap file, you will
have to use a text editor to cut and paste the entries from the
Fontmap in the current directory into the global Fontmap (the location
of this file is dependent on your setup, mine is in
/usr/lib/ghostscript/3.51/Fontmap).  Since the Fontmap entries do not
contain information about which directory the fonts are installed in
you also need to add an entry to the GS_LIB environment variable which
specifies your font directory.  When you next use Ghostscript, these
fonts will then be available.

Important : DO NOT USE THE ENVIRONMENT VARIABLE GS_FONTPATH !!!

Doing this defeats the purpose of using type1inst.  Regardless of what
is in Fontmap, if you use this option Ghostscript will go out and scan
all the fonts in the directories listed in GS_FONTPATH for itself each
time you start it.  The idea is this is only done once.

5.  If you asked for font sample sheets to be generated :

A new directory called "samples" will have been generated with a
series of PostScript files in it.  There is one file for each font in
the directory plus some files called "allfonts-N.ps" (N is a digit)
which are PostScript files containing smaller samples of text from ALL
the fonts.  The single font samples are named after the real name of
the font, not the filename in which they are stored.  For example, I
have ITC Tiepolo Book whose sample file is "samples/Tiepolo-Book.ps",
but the font file itself is called tpw_____.pfb.

There are a couple of very important points which must be made about
the sample sheet feature.

Firstly if you try to send any of these file to a PostScript printer
as they are, chances are the output is not what you expect.  type1inst
does not embed the fonts themselves into the sample file for the
reason that this would use up a large amount of disk space (and most
probably you won't use them regularly anyway).  If you have setup
Ghostscript to find the fonts as described previously then you WILL be
able to view these files correctly if you open them in Ghostview (or
some other previewer based on Ghostscript).  If you do want to print
out the samples or view them with Ghostview (or whatever) on a machine
where the fonts are _not_ installed then you can use the "t1embed"
script to insert the fonts in the sample file.  Simply specify the
filenames of the samples you want with embedded fonts as arguments to
t1embed.  The current version of t1embed requires that the fonts to be
embedded be in the current directory (i.e. it won't look in GS_LIB or
the X font path for files).  In normal usage, therefore, you will want
to run t1embed from the directory with your fonts in it.

Some examples,

  t1embed samples/LucidaSans.ps samples/Tiepolo-Book.ps

embeds LucidaSans and TiepoloBook into their respective sample sheets.

  t1embed samples/*.ps

embeds fonts in all the PostScript files in your samples directory.

Note : As stated above, this is only useful if you are sending files
directly to a PostScript printer.  Printing on a non-PostScript device
usually mean you use GhostScript -- see the section on setting up
GhostScript's Fontmap for details on how to do this.

Note 2 : Distributing PostScript files to others with complete
embedded fonts such as t1embed creates is probably in violation of any
font licensing agreement you have entered into.  You should therefore
keep these files for personal use only.

6.  A log of operations carried out by the script can be found in the
file named "type1inst.log" in the directory in which the script was
run.  If something bad happens, look in here first for more details.


Other Issues
------------

There are some other things that come up when using type1inst and are
discussed below.


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 all font files.  Many fonts say
something in the /Notice string near the top of the font file, and
indeed this is how type1inst attempts to determine the foundry name.
For faces from large vendors like Adobe or Monotype this works fine
99% of the time (the only exception I've seen is for ITC Korinna-Bold
which has a typo in the spelling of "International Typeface
Corporation" ;-) ).  However, you will most probably have some fonts
where this strategy fails.  type1inst will emit a message after it has
finished which looks something 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 or override the foundry name manually
(see the following section).  If, however, a number of your fonts have
similar-looking /Notice strings with a company or person's name, or
something useful 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.  You can do this yourself by reading the
comments near the top of the type1inst script, near the definition of
the array @foundries.

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


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

Some fonts have internal font names which are a little verbose or, 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.  You might want to
abbreviate this to "Courier10" or even "Courier".  Once you have a
valid "fonts.scale" file, you can then edit any part of the X font
specification to be whatever 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.  This way you can make
changes to the file which will be persistent.


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

- The font samples are always re-created if you use the -samples
option.  There is no support just yet for checking to see if the font
has changed and only generating the sample if this is true.

- I consider the current font sample code to be less than ideal.  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 (at the same size) whether they fit or not.  It
also doesn't make any attempt to find out what symbols are in the font.
A future version should 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, as well as making
a sample page with a complete set of available symbols.  Volunteers to
do this are welcome (I have some code if anyone is interested finishing
it).

- 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 fix this if
people using other systems are interested.

- The public domain Hershey fonts which are distributed with Ghostscript
don't have the structure of normal fonts and are ignored.

- Having _lots_ of fonts causes xfontsel's list of fonts to be about five
screens high :-(   [ not my fault ! ]   I have seen an announcement for
a new font previewer for X based on the XView widget set but I have not
tried it.  Look on your local archive sites.

- 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 (need an Xpert).
Perhaps we need to automatically generate aliases or something.

e.g.

artifacts(0):~# xmcd&
[1] 10958
artifacts(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....????)

- Some users in the past reported problems with file globbing not
working, which resulted in the program saying that there are no fonts
in a given directory even though there were some.  I don't know why
this is.  The code now spawns a shell to globbing on behalf of
type1inst which I hope will solve the problem, the logic being if your
shell's globbing is broken then you will have to fix it (unlike perl
which you might not use for anything else).  I have my suspicions
regarding the various versions of the Linux libc which breaks bits and
pieces inside perl.  Please let me know if the problem persists.


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 (until the
end of 1997 anyway) is

J.Macnicol@student.anu.edu.au


Thanks!
-------

My thanks go to the following people for submitting feedback and/or
code.  Apologies to anyone I have forgotten.

Jouni Ahto               
Andreas Dilger 
Andrew Fitzhugh
Inaky Perez Gonzalez
Nathan Hand
Robert Krawitz
Elliot Lee
Daniel Morrison     
Sergei Naumov
James A. Robinson