'\"macro stdmacro
.if n .pH g1.mkiconfont @(#)mkiconfont	40.2 of 12/29/89
.ig
Revised: D. Bodnar 9/7/89
format -dqm4 -man6 -rs1 mkiconfont.1
..
.\" @(#)mkiconfont.1 89/06/15 SMI;
.ds Sd \s-2Ne\h'-0.2n'WS\s+2
.ds Xn X11/Ne\h'-0.2n'WS
.ds Ps P\s-2OST\s+2S\s-2CRIPT\s+2
.nr X
.if \nX=0 .ds x} MKICONFONT 1 "15 June 1989" "\&"
.if \nX=1 .ds x} MKICONFONT 1 "15 June 1989"
.if \nX=2 .ds x} MKICONFONT 1 "" "\&"
.if \nX=3 .ds x} MKICONFONT "" "" "\&"
.TH \*(x}
.IX mkiconfont#(1) "" "\fLmkiconfont\fP(1)" ""
.IX fonts mkiconfont#(1) "" "\fLmkiconfont\fP(1)" ""
.SH NAME
mkiconfont \(em make an 
.SM ASCII 
cursor or icon font from a list of 
.SM ASCII 
bitmap files
.SH SYNOPSIS
.na
\fBmkiconfont\fP [ \fIlistfilename\fP ] [ \fIfontname\fP \fB>\fP \fIfilename\fB.afb\fR ]
.ad
.SH DESCRIPTION
.LP
\fBmkiconfont\fP makes an 
.SM ASCII 
version of the font \fIfontname\fP
from the 
.SM ASCII 
bitmap files that are listed in \fIlistfilename\fP
and puts the output in the file \f2filename\f3.afb\f1.
The convention is to use the suffix \fB.afb\fP for the output file.
The 
.SM ASCII 
bitmap files must conform to a specific format.
.LP
\fBmkiconfont\fP is used to create cursor fonts
and icon fonts.
Each cursor has a cursor image and a mask image that are
superimposed to create the complete cursor. 
To create a cursor font,
first make a bitmap file for the cursor image and another bitmap file
for the mask image.
Then make a list of your cursor image and mask image bitmap files,
and save your list as \fIlistfilename\fP.
Next run \fBmkiconfont\fP,
and then run the output \fIfilename\fB.afb\f1 through the \fBconvertfont\f1(1)
and \fBbldfamily\f1(1) utilities.
Follow the same procedure to make an icon font,
but omit the mask image files.
.SH EXAMPLE
.LP
The font utility \fBmkiconfont\fP expects input in the format
illustrated by the examples below.
Here is an example of an 
.SM ASCII 
bitmap file for a cursor image
named \fBpointer\fP.
Its image is that of a narrow arrow that points up and to the left.
.sp
.ft B
.nf
/* Format_version=1, Width=16, Height=16, Depth=1
 * Valid_bits_per_item=16, XOrigin=0, YOrigin=15
 */
	0x0000,0x4000,0x6000,0x7000,0x7800,0x7C00,0x7E00,0x7800,
	0x4C00,0x0C00,0x0600,0x0600,0x0300,0x0300,0x0180,0x0000
.fi
.ft R
.LP
\fBXOrigin\fP and \fBYOrigin\fP indicate the origin
of the character,
which is the hot-spot of the cursor.
The values for \fBXOrigin\fP and \fBYOrigin\fP originate in the 
bitmap's lower left corner with positive values extending 
up and to the right.
Note that \fBYOrigin\fP starts from the last non-zero row of pixels
rather than from the bottom of the bitmap.
.LP
Here is the 
.SM ASCII 
bitmap file for the mask image of the
\fBpointer\fP cursor.
It is called \fBpointer_mask\fP.
.sp
.ft B
.nf
/* Format_version=1, Width=16, Height=16, Depth=1
 * Valid_bits_per_item=16, XOrigin=0, YOrigin=16
 */
	0xC000,0xE000,0xF000,0xF800,0xFC00,0xFE00,0xFF00,0xFF80,
	0xFE00,0xDF00,0x9F00,0x0F80,0x0F80,0x07C0,0x07C0,0x03C0
.fi
.ft R
.LP
Note that the mask image is used to outline the primary image,
and therefore
its origin is offset by one from the primary image, so as to
superimpose the images correctly.
This arrangement is typical of cursor masks.
.sp
Here is the process for generating a simple cursor font
(the process is the same for generating an icon font,
except that no mask images are needed):
.sp
.IP 1)
Generate a collection of 
.SM ASCII 
bitmap file pairs
with the format described above.
The convention is to call each cursor image
\fIname\fP\fB.cursor\fP and
its mask image \fIname\fP\fB_mask.cursor\fP.
Create a file containing these filenames,
with each name on a separate line.
The pair order should be the cursor image filename on one line
followed by the mask image filename on the next line.
You can give your list any filename.
In this example,
the file is called \fBmyfont.list\fP.
.IP 2)
Make an 
.SM ASCII 
version of the font from the list of 
.SM ASCII
bitmap files using the program \fBmkiconfont\fP.
The first argument to
\fBmkiconfont\fP is the name of the file that contains the list of filenames.
The second argument to \fBmkiconfont\fP is the name of the
output file prepended by a \fB>\fP and the intended name of the
font family.
.sp
.nf
\f3example% mkiconfont myfont.list MyFont>MyFont12.afb\fP
.fi
.IP 3)
Convert the 
.SM ASCII 
version of the font to a binary version using
the program \fBconvertfont\fP(1).
The first argument should be a \fB-d\fP flag
followed by the directory in which you want to put
the resulting binary font file.
You will want to put your output font file in your font
directory;
in this example,
the font directory is 
\fB\s-1$OPENWINHOME\s+1/lib/fonts\fP.
The next argument is the name of the file that contains the 
.SM ASCII
version of the font.
\fBconvertfont\fP names the output file like the 
.SM ASCII 
version,
but it uses a \fB.fb\fP suffix instead of a \fB.afb\fP suffix.
In this example,
the 
.SM ASCII 
version is in the file called \fBMyFont12.afb\fP,
and the output file that \fBconvertfont\fP produces is called
\fBMyFont12.fb\fP.
.sp
.B "example% convertfont -d\s-1$OPENWINHOME\s+1/lib/fonts MyFont12.afb\fP"
.ft 1
.IP 4)
Build a font family file for the font, using the program
\fBbldfamily\fP(1).
The only argument to \fBbldfamily\fP is the name of the
directory in which the font files are located.
\fBbldfamily\fP looks in the specified directory for files
with extensions \fB.fb\fP and \fB.fm\fP and constructs
a \*(Sd font family file for each group of fonts with the
same family name.
.sp
.nf
\f3example% bldfamily -d\s-1$OPENWINHOME\s+1/lib/fonts\fP
.fi
.IP 5)
Create a \fB.ps\fP file
that contains a dictionary of character names for the font.
The \fB.afb\fP and \fB.fb\fP files associate a number with each
character in the font;
it is more convenient to associate the name of each
bitmap file with the character that it represents.
The following example shows one way to build such a \fB.ps\fP file.
.sp
.ft B
.nf
	#! /bin/sh
	egrep "^(\s-1STARTCHAR|ENCODING\s+1)" MyFont12.afb>myfont.ps
	ed - myfont.ps<<'\s-1EOF\s+1t'
	g/\s-1STARTCHAR\s+1/j
	1,$s'\s-1STARTCHAR\s+1 *\e(.*\)\s-1ENCODING\s+1 *\e(.*\e)'/\e1 /\e2 def'
	1i
	/myfontdict 300 dict def
	myfontdict begin
	.
	$a
	end
	/showmyfont {
        	currentfont ( ) dup 0 myfontdict 5 index get put
	        myfontfont setfont show setfont pop } def
	/myfont (MyFont) findfont 12 scalefont def
	.
	w
	q
	\s-1EOT\s+1
.fi
.sp
\f1Another way to implement the name association is
to have \fBmkiconfont\fP build the \fB.ps\fP file;
this method is also a valid implementation.
.IP 6)
Copy the \fB.ps\fP file to a well-known place.
.sp
.ft B
.nf
example% cp myfont.ps \s-1$OPENWINHOME\s+1/lib/\s-1N\s+1e\s-1WS\s+1
.fi
.ft R
.IP 7)
Use the \fB.ps\fP file before you use the font
in your \*(Ps program.
.sp
.ft B
.nf
	(\s-1N\s+1e\s-1WS\s+1/myfont.ps) run
	myfontdict begin
	name name_mask myfont newcursor
	end
.fi
.sp
\f1Note that your \fB.ps\fP file created the dictionary
\fBmyfontdict\fP for you.
You can then push the dictionary on the stack and use it
in the normal way.
.SH SEE ALSO
.na
\fBbldfamily\fP(1), \fBconvertfont\fP(1)
.ad
.SH FUTURE DIRECTIONS
.LP
In the future,
\fBmkiconfont\fP will be replaced with a more
sophisticated font editing tool.
The new tool will be useful for creating any new font,
rather than just being useful for fonts with a limited number
of characters such as icons and cursors.
