<!-- $Id: fonts.docb,v 1.1 1997-02-15 18:02:20 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!DOCTYPE BOOK PUBLIC "-//Davenport//DTD DocBook V3.0//EN">

<!-- Recently, I wanted to figure out how to use some additional fonts that
     I had accumulated.  I finally figured out *how to do it* from the various
     man pages and documentation.  Since it might be of use to other users,
     and I didn't see any reference to this topic in the FAQ or handbook, I
     thought I'd try my hand at a simple cookbook tutorial addressing the
     use of fonts.  I have included my unanswered questions at the end of
     the document.

     Anyway, here's what I put together.  This is my present understanding of
     fonts and how to use them with FreeBSD.  I am sure that there are errors or
     misunderstandings, but it contains enough valid information to allow the
     use of additional fonts with Ghostscript, X11 and Groff.  This is my first
     attempt to write anything along the lines of a tutorial/FAQ, so I am sure
     it is pretty raw.  There are probably better ways to do some of this stuff,
     and I would welcome being corrected.
 -->

<book>

<bookinfo>
<bookbiblio>
<title>Fonts and FreeBSD</title>
<subtitle>A Tutorial</subtitle>

<authorgroup>
<author>
<firstname>Dave</firstname>
<surname>Bodenstab</surname>
<affiliation>
<address><email>imdave@synet.net</email></address>
</affiliation>
</author>
</authorgroup>

<pubdate>Wed Aug  7, 1996</pubdate>

<abstract><para>This document contains a description of the various
font files that may be used with FreeBSD and the syscons driver, X11,
Ghostscript and Groff. Cookbook examples are provided for switching
the syscons display to 80x60 mode, and for using type 1 fonts with
the above application programs.</para></abstract>

</bookbiblio>
</bookinfo>

<chapter>
<title>Introduction</title>

<para>There are many sources of fonts available, and one might ask
how they might be used with FreeBSD. The answer can be found by
carefully searching the documentation for the component that one
would like to use. This is very time consuming, so this tutorial is
an attempt to provide a shortcut for others who might be
interested.</para>

</chapter>

<chapter>
<title>Basic terminology</title>

<para>There are many different font formats and associated font file
suffixes. A few that will be addressed here are:
<variablelist>

<varlistentry><term><filename>.pfa</>, <filename>.pfb</></term>

<listitem><para>Postscript type 1 fonts.  The <filename>.pfa</filename> is the
<emphasis>A</emphasis>scii form and <filename>.pfb</filename> the
<emphasis>B</emphasis>inary form.</para></listitem>

</varlistentry>

<varlistentry><term><filename>.afm</></term>

<listitem><para>The font metrics associated with a type 1
font.</para></listitem>

</varlistentry>

<varlistentry><term><filename>.pfm</></term>

<listitem><para>The printer font metrics associated with a type 1
font.</para></listitem>

</varlistentry>

<varlistentry><term><filename>.ttf</></term>

<listitem><para>A TrueType font</para></listitem>

</varlistentry>

<varlistentry><term><filename>.fot</></term>

<listitem><para>An indirect reference to a TrueType font (not an
actual font)</para></listitem>

</varlistentry>

<varlistentry><term><filename>.fon</>, <filename>.fnt</></term>

<listitem><para>Bitmapped screen fonts</para></listitem>

</varlistentry>
</variablelist></para>
  
<para>The <filename>.fot</filename> file is used by Windows as sort
of a symbolic link to the actual TrueType font
(<filename>.ttf</filename>) file.  The <filename>.fon</filename> font
files are also used by Windows. I know of no way to use this font
format with FreeBSD.</para>

</chapter>

<chapter>
<title>What font formats can I use?</title>

<para>Which font file format is useful depends on the application
being used. FreeBSD by itself uses no fonts.  Application programs
and/or drivers may make use of the font files.  Here is a small cross
reference of application/driver to the font type suffixes:</para>

<para>
<variablelist>
<varlistentry><term>Driver</term>
<listitem>
<para>
<variablelist>
<varlistentry><term>syscons</term>
<listitem>
<para><filename>.fnt</></para>
  
</listitem>
</varlistentry>
</variablelist>
</para>
  
</listitem>
</varlistentry>

<varlistentry><term>Application</term>

<listitem>
<para>
<variablelist>
<varlistentry><term>Ghostscript</term>
<listitem>
<para><filename>.pfa</filename>, <filename>.pfb</filename>, <filename>.ttf</filename></para>
  
</listitem>
</varlistentry>

<varlistentry><term>X11</term>

<listitem>
<para><filename>.pfa</filename>, <filename>.pfb</filename></para>
  
</listitem>
</varlistentry>

<varlistentry><term>Groff</term>

<listitem>
<para><filename>.pfa</filename>, <filename>.afm</filename></para>
  
</listitem>
</varlistentry>

<varlistentry><term>Povray</term>

<listitem>
<para><filename>.ttf</filename></para>
  
</listitem>
</varlistentry>
</variablelist>
</para>
  
</listitem>
</varlistentry>
</variablelist>
</para>
  
<para>The <filename>.fnt</filename> suffix is used quite frequently. 
I suspect that whenever someone wanted to create a specialized font
file for their application, more often than not they chose this
suffix.  Therefore, it is likely that files with this suffix are not
all the same format; specifically, the <filename>.fnt</filename>
files used by syscons under FreeBSD may not be the same format as a
<filename>.fnt</filename> file one encounters in the MSDOS/Windows
environment.  I have not made any attempt at using other
<filename>.fnt</filename> files other than those provided with
FreeBSD.</para>

</chapter>

<chapter>
<title>Setting a virtual console to 80x60 line mode</title>

<para>First, a 8x8 font must be loaded. 
<filename>/etc/sysconfig</filename> should contain the lines:
<informalexample>
<programlisting># Choose font 8x8 from /usr/share/syscons/fonts/* (or NO for default)
font8x8=/usr/share/syscons/fonts/cp437-8x8.fnt</programlisting>
</informalexample>
</para>
  
<para>The command to actually switch the mode is
<citerefentry><refentrytitle>vidcontrol</><manvolnum>1</></>:
<informalexample>
<screen>bash$ <userinput>vidcontrol VGA_80x60</userinput></screen>
</informalexample>
</para>
  
<para>Various screen orientated programs, such as
<citerefentry><refentrytitle>vi</><manvolnum>1</></>, must be able to
determine the current screen dimensions.  These can be set with
<citerefentry><refentrytitle>stty</><manvolnum>1</></>:
<informalexample>
<screen>bash$ <userinput>stty crt rows 60 columns 80</userinput></screen>
</informalexample>
</para>
  
<para>To make this more seamless, one can embed these commands in the
startup scripts so it takes place when the system boots.  One way to
do this is:
<orderedlist>

<listitem>
<para>Modify <filename>/etc/sysconfig</filename> as above</para>
</listitem>

<listitem>
<para>Add to <filename>/etc/rc.local</filename>:
<informalexample>
<programlisting>for tty in /dev/ttyv?
do
  vidcontrol VGA_80x60 &lt;$tty &gt;/dev/null 2&gt;&amp;1
done</programlisting>
</informalexample></para>
</listitem>

<listitem>
<para>Add to <filename>/etc/profile</filename>:
<informalexample>
<programlisting>TTYNAME=`basename \`tty\``
if expr "$TTYNAME" : 'ttyv' &gt;/dev/null
then
  stty crt rows 60 columns 80
fi</programlisting>
</informalexample>
</para>
</listitem>

</orderedlist>
</para>
  
<para>References:
<citerefentry><refentrytitle>stty</><manvolnum>1</></>,
<citerefentry><refentrytitle>vidcontrol</><manvolnum>1</></>.</para>

</chapter>

<chapter>
<title>Using type 1 fonts with X11</title>

<para>X11 can use either the <filename>.pfa</filename> or the
<filename>.pfb</filename> format fonts.  The X11 fonts are located in
various subdirectories under
<filename>/usr/X11R6/lib/X11/fonts</filename>.  Each font file is
cross referenced to its X11 name by the contents of the
<filename>fonts.dir</filename> file in each directory.</para>

<para>There is already a directory named <filename>Type1</>. The most
straight forward way to add a new font is to put it into this
directory.  A better way is to keep all new fonts in a separate
directory and use a symbolic link to the additional font.  This
allows one to more easily keep track of ones fonts without confusing
them with the fonts that were originally provided.  For
example:
<informalexample>
<screen><lineannotation>Create a directory to contain the font files</>
bash$ <userinput>mkdir -p /usr/local/share/fonts/type1</>
bash$ <userinput>cd /usr/local/share/fonts/type1</>

<lineannotation>Place the .pfa, .pfb and .afm files here</>
<lineannotation>One might want to keep readme files, and other documentation</>
<lineannotation>for the fonts here also</>
bash$ <userinput>cp /cdrom/fonts/atm/showboat/showboat.pfb .</>
bash$ <userinput>cp /cdrom/fonts/atm/showboat/showboat.afm .</>

<lineannotation>Maintain an index to cross reference the fonts</>
bash$ <userinput>echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat &gt;&gt;INDEX</></screen>
</informalexample>
</para>
  
<para>Now, to use a new font with X11, one must make the font file
available and update the font name files.  The X11 font names look
like:
<informalexample>
<screen>-bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1
     |        |      |    |   |     |  | | | | | |    \    \ 
     |        |      |    |   |     \  \ \ \ \ \ \     +----+- character set
     |        |      |    |   \      \  \ \ \ \ \ +- average width
     |        |      |    |    \      \  \ \ \ \ +- spacing
     |        |      |    \	\      \  \ \ \ +- vertical res.
     |        |      |     \	 \	\  \ \ +- horizontal res.
     |        |      |      \	  \	 \  \ +- points
     |        |      |       \     \	  \  +- pixels
     |        |      |        \     \	   \
  foundry  family  weight   slant  width  additional style</screen>
</informalexample>
</para>
  
<para>A new name needs to be created for each new font.  If you have
some information from the documentation that accompanied the font,
then it could serve as the basis for creating the name.  If there is
no information, then you can get some idea by using
<citerefentry><refentrytitle>strings</><manvolnum>1</></> on the font
file.  For example:
<informalexample>
<screen>bash$ <userinput>strings showboat.pfb | more</>
%!FontType1-1.0: Showboat 001.001
%%CreationDate: 1/15/91 5:16:03 PM
%%VMusage: 1024 45747
% Generated by Fontographer 3.1
% Showboat
 1991 by David Rakowski.  Alle Rechte Vorbehalten.
FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup
/UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse
{save true}{false}ifelse}{false}ifelse
12 dict begin
/FontInfo 9 dict dup begin
 /version (001.001) readonly def
 /FullName (Showboat) readonly def
 /FamilyName (Showboat) readonly def
 /Weight (Medium) readonly def
 /ItalicAngle 0 def
 /isFixedPitch false def
 /UnderlinePosition -106 def
 /UnderlineThickness 16 def
 /Notice (Showboat
 1991 by David Rakowski.  Alle Rechte Vorbehalten.) readonly def
end readonly def
/FontName /Showboat def
--stdin--</screen>
</informalexample></para>
  
<para>Using this information, a possible name might be:
<informalexample>
<screen>-type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1</screen>
</informalexample>
</para>
  
<para>The components of our name are:
<variablelist>

<varlistentry><term>Foundry</term>
<listitem>
<para>Lets just name all the new fonts <literal>type1</>.</para>
</listitem>
</varlistentry>

<varlistentry><term>Family</term>
<listitem>
<para>The name of the font.</para>
</listitem>
</varlistentry>

<varlistentry><term>Weight</term>
<listitem>
<para>Normal, bold, medium, semibold, etc.  From the
<citerefentry><refentrytitle>strings</><manvolnum>1</></> output
above, it appears that this font has a weight of
<emphasis>medium</emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry><term>Slant</term>
<listitem>
<para><emphasis remap=bf>r</emphasis>oman, <emphasis
remap=bf>i</emphasis>talic, <emphasis remap=bf>o</emphasis>blique,
etc.  Since the <emphasis>ItalicAngle</emphasis> is zero,
<emphasis>roman</emphasis> will be used.</para>
</listitem>
</varlistentry>

<varlistentry><term>Width</term>
<listitem>
<para>Normal, wide, condensed, extended, etc.  Until it can be examined,
the assumption will be <emphasis>normal</emphasis>.</para>
</listitem>
</varlistentry>

<varlistentry><term>Additional style</term>
<listitem>
<para>Usually omitted, but this will indicate that
the font contains decorative capital letters.</para>
</listitem>
</varlistentry>

<varlistentry><term>Spacing</term>
<listitem>
<para>proportional or monospaced.  <emphasis>Proportional</emphasis>
is used since <emphasis>isFixedPitch</emphasis> is false.</para>
</listitem>
</varlistentry>

</variablelist>
</para>
  
<para>All of these names are arbitrary, but one should strive to be
compatible with the existing conventions.  A font is referenced by
name with possible wild cards by an X11 program, so the name chosen
should make some sense. One might begin by simply using
<informalexample>
<screen>&hellip;-normal-r-normal-&hellip;-p-&hellip;</screen>
</informalexample>
as the name, and then use
<citerefentry><refentrytitle>xfontsel</><manvolnum>1</></> to examine it
and adjust the name based on the appearance of the font.</para>

<para>So, to complete our example:
<informalexample>
<screen><lineannotation>Make the font accessible to X11</>
bash$ <userinput>cd /usr/X11R6/lib/X11/fonts/Type1</>
bash$ <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</>

<lineannotation>Edit fonts.dir and fonts.scale, adding the line describing the font
and incrementing the number of fonts which is found on the first line.</>
bash$ <userinput>ex fonts.dir
:1p
25
:1c
26
.
:$a
showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1
.
:wq</>

<lineannotation><filename>fonts.scale</> seems to be identical to <filename>fonts.dir</>&hellip;</>
bash$ <userinput>cp fonts.dir fonts.scale</>

<lineannotation>Tell X11 that things have changed</>
bash$ <userinput>xset fp rehash</>

<lineannotation>Examine the new font</>
bash$ <userinput>xfontsel -pattern -type1-*</></screen>
</informalexample>
</para>
  
<para>References:
<citerefentry><refentrytitle>xfontsel</><manvolnum>1</></>,
<citerefentry><refentrytitle>xset</><manvolnum>1</></>,
<citetitle>The X Windows System in a Nutshell</>, <ulink
URL="http://www.ora.com/">O'Reilly &amp; Associates</ulink>.</para>

</chapter>

<chapter>
<title>Using type 1 fonts with Ghostscript</title>

<para>Ghostscript references a font via its <filename>Fontmap</>
file.  This must be modified in a similar way to the X11
<filename>fonts.dir</filename> file.  Ghostscript can use either the
<filename>.pfa</filename> or the <filename>.pfb</filename> format
fonts.  Using the font from the previous example, here is how to use
it with Ghostscript:
<informalexample>
<screen><lineannotation>Put the font in Ghostscript's font directory</>
bash$ <userinput>cd /usr/local/share/ghostscript/fonts</>
bash$ <userinput>ln -s /usr/local/share/fonts/type1/showboat.pfb .</>

<lineannotation>Edit Fontmap so Ghostscript knows about the font</>
bash$ <userinput>cd /usr/local/share/ghostscript/4.01</>
bash$ <userinput>ex Fontmap
:$a
/Showboat        (showboat.pfb) ; % From CICA /fonts/atm/showboat
.
:wq</>

<lineannotation>Use Ghostscript to examine the font</>
bash$ <userinput>gs prfont.ps</>
Aladdin Ghostscript 4.01 (1996-7-10)
Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA.  All rights
reserved.
This software comes with NO WARRANTY: see the file PUBLIC for details.
Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb...
 /1899520 581354 1300084 13826 0 done.
GS&gt;<userinput>Showboat DoFont</>
Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb...
 1939688 565415 1300084 16901 0 done.
&gt;&gt;showpage, press &lt;return&gt; to continue&lt;&lt;
&gt;&gt;showpage, press &lt;return&gt; to continue&lt;&lt;
&gt;&gt;showpage, press &lt;return&gt; to continue&lt;&lt;
GS&gt;<userinput>quit</></screen>
</informalexample>
</para>
  
<para>References: <filename>fonts.txt</filename> in the Ghostscript
4.01 distribution</para>

</chapter>

<chapter>
<title>Using type 1 fonts with Groff</title>

<para>Now that the new font can be used by both X11 and Ghostscript,
how can one use the new font with groff?  First of all, since we are
dealing with type 1 postscript fonts, the groff device that is
applicable is the <emphasis>ps</emphasis> device. A font file must be
created for each font that groff can use.  A groff font name is just
a file in <filename>/usr/share/groff_font/devps</filename>.  With our
example, the font file could be
<filename>/usr/share/groff_font/devps/SHOWBOAT</filename>.  The file
must be created using tools provided by groff.</para>

<para>The first tool is <command>afmtodit</>.  This is not normally
installed, so it must be retrieved from the source distribution.  I
found I had to change the first line of the file, so I did:
<informalexample>
<screen>bash$ <userinput>cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp</>
bash$ <userinput>ex /tmp/afmtodit.pl
:1c
#!/usr/bin/perl -P-
.
:wq</></screen>
</informalexample>
</para>
  
<para>This tool will create the groff font file from the metrics file
(<filename>.afm</filename> suffix.) Continuing with our
example:
<informalexample>
<screen><lineannotation>Many <filename>.afm</> files are in Mac format&hellip ^M delimited lines
We need to convert them to unix style ^J delimited lines</>
bash$ <userinput>cd /tmp</>
bash$ <userinput>cat /usr/local/share/fonts/type1/showboat.afm |
	tr '\015' '\012' &gt;showboat.afm</>

<lineannotation>Now create the groff font file</>
bash$ <userinput>cd /usr/share/groff_font/devps</>
bash$ <userinput>/tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT</></screen>
</informalexample>
</para>
  
<para>The font can now be referenced with the name SHOWBOAT.</para>
  
<para>If ghostscript is used to drive the printers on the system,
then nothing more needs to be done.  However, if true postscript
printers are used, then the font must be down loaded to the printer
in order for the font to be used (unless the printer happens to have
the showboat font built in or on an accessible font disk.) The final
step is to create a down loadable font. The <command>pfbtops</> tool
is used to create the <filename>.pfa</filename> format of the font,
and the <filename>download</> file is modified to reference the new
font.  The <filename>download</> file must reference the internal
name of the font.  This can easily be determined from the groff font
file as illustrated:
<informalexample>
<screen><lineannotation>Create the <filename>.pfa</> font file</>
bash$ <userinput>pfbtops /usr/local/share/fonts/type1/showboat.pfb &gt;showboat.pfa</></screen>
</informalexample>
Of course, if the <filename>.pfa</filename> file is already
available, just use a symbolic link to reference it.
<informalexample>
<screen><lineannotation>Get the internal font name</>
bash$ <userinput>fgrep internalname SHOWBOAT</>
internalname Showboat

<lineannotation>Tell groff that the font must be down loaded</>
bash$ <userinput>ex download
:$a
Showboat      showboat.pfa
.
:wq</></screen>
</informalexample>
</para>
  
<para>To test the font:
<informalexample>
<screen>bash$ <userinput>cd /tmp</>
bash$ <userinput>cat &gt;example.t &lt;&lt;EOF
.sp 5
.ps 16
This is an example of the Showboat font:
.br
.ps 48
.vs (\n(.s+2)p
.sp
.ft SHOWBOAT
ABCDEFGHI
.br
JKLMNOPQR
.br
STUVWXYZ
.sp
.ps 16
.vs (\n(.s+2)p
.fp 5 SHOWBOAT
.ft R
To use it for the first letter of a paragraph, it will look like:
.sp 50p
\s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the
showboat font as its first letter.
Additional vertical space must be used to allow room for the larger
letter.
EOF</>
bash$ <userinput>groff -Tps example.t &gt;example.ps</>

<lineannotation>To use ghostscript/ghostview</>
bash$ <userinput>ghostview example.ps</>

<lineannotation>To print it</>
bash$ <userinput>lpr -Ppostscript example.ps</></screen>
</informalexample>
</para>
  
<para>References:
<filename>/usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man</filename>,
<citerefentry><refentrytitle>groff_font</><manvolnum>5</></>,
<citerefentry><refentrytitle>groff_char</><manvolnum>5</></>, 
<citerefentry><refentrytitle>pfbtops</><manvolnum>1</></>.</para>
  
</chapter>

<chapter>
<title>Can TrueType fonts be used?</title>

<para>The TrueType font format is used by Windows, Windows 95,
Mac's,&hellip  It is quite popular and there are a great number of
fonts available in this format. Unfortunately, there are only two
applications that I am aware of that can use this format: Ghostscript
and povray.  Ghostscript's support, according to the documentation,
is rudimentary and the results are likely to be inferior to type 1
fonts.</para>

<para>However, groff would need a font description file, and I know
of no tools to construct the metrics from a TrueType font.  In
addition, the font would have to be down loaded to postscript
printers in the appropriate format, and again, groff cannot handle
TrueType fonts in this fashion.</para>

<para>X11 has no support for TrueType fonts that I am aware
of.</para>

<para>The only program that I know of that has the ability to use
TrueType fonts is povray version 3, but I rather doubt many people
will be creating documents as a series of raytraced pages!  
:-)</para>

</chapter>

<chapter>
<title>Where can additional fonts be obtained?</title>

<para>Many fonts are available on the Internet.  They are either
entirely free, or are share-ware.  In addition, there are many
inexpensive CDROMs available that contain many fonts.  Some Internet
locations (as of August 1996) are:
<itemizedlist>

<listitem><para><ulink
url="ftp://ftp.winsite.com">ftp://ftp.winsite.com</ulink> (Formerly
CICA)</para></listitem>

<listitem><para><ulink
url="http://www.simtel.net/simcgi-bin/dosfind.cgi">http://www.simtel.net/simcgi-bin/dosfind.cgi</ulink></para></listitem>

<listitem><para><ulink
url="ftp://ftp.coast.net/">ftp://ftp.coast.net/</ulink></para></listitem>

<listitem><para><ulink
url="http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html">http://af-pc-plloyd.ecel.uwa.edu.au/fonts/index.html</ulink></para></listitem>

<listitem><para><ulink
url="http://www.esselte.com/letraset/index.html">http://www.esselte.com/letraset/index.html</ulink></para></listitem>

<listitem><para><ulink
url="http://www.inil.com/users/elfring/esf.htm">http://www.inil.com/users/elfring/esf.htm</ulink></para></listitem>

</itemizedlist></para>
  
</chapter>

<chapter>
<title>Additional questions</title>

<para>
<itemizedlist>

<listitem>
<para>What use are the <filename>.pfm</filename> files?</para>
</listitem>

<listitem>
<para>Can one generate the <filename>.afm</filename> file from a <filename>.pfa</filename> or <filename>.pfb</filename>?</para>
</listitem>

<listitem>
<para>How to generate the groff character mapping files for postscript fonts
with non-standard character names?</para>
</listitem>

<listitem>
<para>Can xditview and devX?? devices be setup to access all the new fonts?</para>
</listitem>

<listitem>
<para>It would be good to have examples of using TrueType fonts with povray and
ghostscript.</para>
</listitem>

</itemizedlist>
</para>
  
</chapter>
</book>
