\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename ogonkify.info
@settitle Ogonkify
@setchapternewpage off
@c %**end of header

@c Time-stamp: <99/05/14 04:30:20 jec>

@dircategory Printing Tools
@direntry
* ogonkify: (ogonkify).            Ogonkify
@end direntry

@ifinfo
This is the Ogonkify manual, Copyright @copyright{} 1996--1999 by
Juliusz Chroboczek.
@end ifinfo

@titlepage
@title Ogonkify
@author Juliusz Chroboczek
@end titlepage

@node Top, License, (dir), (dir)

@top The Ogonkify package

The Ogonkify package contains two programs: a utility for adding
composite characters to fonts in a semi-automatic fashion, and a program
for converting PS output --- notably Netscape and Mosaic output --- to use
these fonts.

@menu
* License::                     Your rights and my polite requests
* Using Ogonkify::              How to use Ogonkify
* Adding new characters::       How to add new characters to the fonts
* Reaching the author::         Addresses
@end menu

@node License, Using Ogonkify, Top, Top
@chapter The McKornik Jr.@: Public License

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

In particular, this program is provided as is, without any warranty, not
even of any kind.  It might (or might not) do what it is supposed to do,
it might (or might not) destroy your printer, and it might (or might
not) be useful to you.  In any case, you are on your own.

This program is written in Perl.  While stronger people find reading
Perl code character-building, it should not be shown to people in their
formative years.  The author will not accept any responsibility for any
moral grief caused.

I would like to ask you @emph{not} to distribute the generated fonts
without including a pointer to the original AFMs and the rest of the
code.  Furthermore, please notify me if you decide to include this code
in a larger piece of software.

If you find this software useful, local goodies, makowiec, beer from
Zywiec, postcards from exotic places and all sorts of things are
accepted.

@node Using Ogonkify, Adding new characters, License, Top
@chapter Using Ogonkify

This chapter describes the various uses of Ogonkify.

@menu
* Ghostscript::                 Viewing with ghostscript
* Standard Applications::       Using the package with standard applications
* a2ps::                        Printing with a2ps
* genscript::                   Printing with genscript
@end menu

@node Ghostscript, Standard Applications, Using Ogonkify, Using Ogonkify
@section Viewing with Ghostscript

Due to a bug in some versions of ghostscript, in order to view the
output of Ogonkify you may need to run ghostscript with the
@code{-dNOPLATFONTS} option, as in

@example
gs -dNOPLATFONTS foo.ps
@end example

@noindent
or in

@example
ghostview -arguments -dNOPLATFONTS foo.ps
@end example

See the @code{gs(1)} and @code{ghostview(1)} manual pages for more
details.

@node Standard Applications, a2ps, Ghostscript, Using Ogonkify
@section Printing from Standard Applications

The main use of Ogonkify is to allow various standard applications to
print in various languages.  As of this writing, the @code{ogonkify}
script knows how to handle Netscape, Mosaic, the mail printer MP,
StarOffice, and ApplixWare.  Its usage is described in full detail in
the @code{ogonkify(1)} manual page.

@node a2ps, genscript, Standard Applications, Using Ogonkify
@section Printing with a2ps

@code{a2ps} is a PostScript formatter with pretty-printing capabilities.
Starting with version 4.7.21, it automatically uses Ogonkify,
which is distributed with it. @xref{top,,a2ps manual,a2ps.info,a2ps manual}.

@code{a2ps} can be obtained from:

@example
<URL:http://www-stud.enst.fr/~demaille/a2ps.html>
@end example

@node genscript,  , a2ps, Using Ogonkify
@section Printing with GNU Enscript

GNU Enscript is a program for printing text files on PostScript printers
written by Markku Rossi and distributed with other GNU software.  You
will find it on any mirror carrying GNU software.

GNU Enscript is one of the few programs that allow the user to select
the encoding of the files he wants to print, and correctly reencoding
the fonts it uses .  In order to obtain information about the characters
available in a font, it uses AFM files.

If you are only interested in printing in Courier, you might want to
simply use the IBM Courier fonts and the AFM files provided with them.
However, you may also want to use the output of Ogonkify; for
printing in Times and Helvetica, this is the only solution.

Here are installation procedures for using the fonts generated by the
@code{instogonki} script with @code{genscript}.  They assume that
@code{genscript} is properly installed, and that you know which
@code{genscript.cfg} file it reads.

@enumerate

@item In the directory @code{$PFADIR}, type
@example
% mkafmmap *.afm
@end example
(the @code{mkafmmap} program is installed with GNU Enscript).

@item In the @code{genscript.cfg} file, add your @code{$PFADIR} directory
to the AFMPath.
@end enumerate

@noindent
You can now print with the composite characters.  Example:
@example
% genscript -X latin2 -f Times-Roman-Ogonki@@12 \
            -o wierszyk.ps wierszyk.txt
@end example
or
@example
% genscript -X latin2 -f Helvetica-Ogonki@@12 \
            -o wierszyk.ps wierszyk.txt
@end example


@node Adding new characters, Reaching the author, Using Ogonkify, Top
@chapter Adding new characters

This chapter attempts to explain how to extend Ogonkify to handle
supplementary characters.

@menu
* Composite background::        Background about composite characters
* AFM files::                   Non-orthodox use of Adobe Font Metric files
* Generated fonts::             Fonts with composite characters
* Composite usage::             Usage of the script `composeglyphs'
* Composite example::           A step-by-step example
@end menu

@node Composite background, AFM files, Adding new characters, Adding new characters

@section Background

A typical Type 1 font for the latin alphabet contains ``pure''
characters, such a @code{A} or @code{acute}, and composite characters,
such as @code{Aacute}, which are composed of the @code{A} character, and
the @code{acute} character using the Type 1 @code{seac} operator.

Unfortunately, most fonts do not contain all the characters in the ISO
Latin-2 character set.  In particular, most of the Polish characters
(with the exception of @code{oacute} and @code{Oacute}) are usually
missing (a notable exception is IBM Courier --- not Adobe Courier ---
which contains many useful glyphs).  However, the components of those
glyphs are present.  It should not be difficult to add the
characters we need if the necessary tools were available@dots{} At least
four methods could be used:

@noindent
i) Do not change the original font, but do overstriking for individual
characters (e.g. typeset an @code{a}, then move backwards and typeset an
@code{ogonek} for @code{aogonek}).  This method is widely used, for
instance by TeX.

@noindent
ii) Parse the @code{PFA} or @code{PFB} file containing the font
program for a Type 1 font, and generate a new @code{PFA} containing the
composite characters.  This should not be too difficult (@code{PFA}
parsers are freely available), but would require that users have the
@code{PFA} files corresponding to the fonts they use, which is often
not the case. Furthermore, I believe that it would violate the license
of the fonts.  I am not quite sure what to make of the following:
@quotation
Adobe Systems' Type 1 font programs are licensed for use on one or
more devices (depending on the terms of particular licenses).
These licenses would permit the use of a licensed program in a
system that translates a Type 1 font program to some other format
in the process of rendering, as long as a copy of the program
(even in translated form) is not produced.
@flushright
@cite{Adobe Type 1 Font Format}, p.@: 7, Adobe Systems Inc.
@end flushright
@end quotation

@noindent
iii) Download the original font, and add to its Charstrings dictionary
the supplementary characters using PostScript.  This would not violate
the license agreement as the modified font would exist only in the
printer.  However, many PostScript interpreters do not allow tampering
with Type 1 font dictionaries.  Copy protection, as always, only bothers
honest users.

@noindent
iv) Create a new Type 3 font dictionary which draws characters by
using the characters in the original font.  This has the benefits of
working and being legal.  I expected it to be quite inefficient, but
found it to be reasonably fast.

The @code{composite.ps} file contained in this distribution, and the
accompanying perl program @code{composeglyphs}, follow scheme (iv).  The
following sections describe them in more detail, including information
on extending the code to create other composite characters.

@quotation
@strong{Please note:} our usage of the word ``composite'' has noting to
do with Adobe's notion of ``composite fonts''.  This is a bug.
@end quotation

@quotation
@strong{Please note:} a Polish typographer would be appalled to see that
we consider the ``ogonek'' as a diacritical mark, and thus harm the
integrity of the two letters that all Poles love.  Indeed, in a proper
Polish font, the tail of @code{aogonek} would have a different shape
than that of @code{eogonek}.  Considering however the poor availability
of fonts with the needed characters, we do not currently have the luxury
to whine about such esthetic problems.
@end quotation

@node AFM files, Generated fonts, Composite background, Adding new characters
@section Non-orthodox uses of Adobe Font Metrics files

Information about the fonts comes from @dfn{Adobe Font Metrics} (AFM)
files.  Much more information is in AFMs then usually known; in
particular, the encoding vector can be derived from the AFM, and AFMs
contain the composite character information.  Therefore, a program could
generate the needed font --- encoding vector and everything included ---
from the AFMs.

In order to simplify the handling of AFM information, we use three
different AFMs on every run of the program: (i) an AFM with the encoding
vector to use, (ii) the AFM of the original font, and (iii) an AFM with
supplementary composite character information.  The latter will usually
have to be supplied by the user.  It is needed because AFMs provided
with Type 1 fonts usually only contain composite information about the
characters already in the font (in fact, the Adobe documentation does
not make it quite clear whether it is legal to insert composite
information about characters not already in the font into an AFM).


@node Generated fonts, Composite usage, AFM files, Adding new characters
@section Fonts with composite characters

The generated font contains (i) the characters that were in the original
font, and (ii) the characters which were not in the original font but
for which composite information was provided.  AFM files for the
generated fonts are generated too, which means that the fonts can be
used with most applications.  Furthermore, they can be reencoded, just
like any well-behaved PostScript font.

In order to maintain compatibility with PostScript Level 1, every
composed font must be based on a base encoding vector, and characters
can only be composed from components in that vector.  Thus, in order
to build @code{Nacute} from @code{N} and @code{acute}, both @code{N} and
@code{acute} must be in the base vector.

However, as the base vector is only ever used internally, much liberty
can be taken when designing it.  In particular, it doesn't need to be
compatible with any other vector, and there is no reason to avoid the
control character range.  The base encoding vector that I use is called
@code{OgonkiEncoding}; it is based on Latin-2, but contains all the
characters of @code{StandardEncoding} (although in strange places).

There is a limitation on the composite information that can be used.
In particular, the only composite entries used are of the form:

@example
CC ... 2 ; PCC x 0 0 ; PCC ' ... ; ...
@end example

@noindent
In plain words, there must be exactly two characters to compose, the
first character must be set at the origin, and the width of the
composite character is taken to be that of the first character.  This
limitation is easy to lift, and I will generalize the code if you send
me AFMs that do not obey this convention (I have never seen any, and,
indeed, this is the format required by the Type 1 @code{seac} operator).
AFMs that do not obey it are (hopefully) gracefully handled (you should
see warnings about @code{CC} entries being ignored).


@node Composite usage, Composite example, Generated fonts, Adding new characters
@section Usage of the composite script

The @code{composeglyphs} script can be run to generate either an encoding
vector or a new font.  It is a perl script, and only reformats the data;
the real magic is in the file @code{composite.ps}.

In order to generate an encoding vector from a suitable AFM,
@code{composeglyphs} is run as follows:

@example
% composeglyphs -e latin2.afm -E latin2.enc
@end example

@noindent
which will generate the file @code{latin2.enc} from the AFM file
@code{latin2.afm} (this is the default).  Any AFM file is suitable as
input, but most AFMs do not contain all the possible characters of an
encoding vector (the missing ones will be replaced by @code{.notdef}).

In order to generate a font program, more input must be provided:

@example
% composeglyphs -i ptmr.afm -c ptmr-c.afm \
                -o ptmr-o.ps -n Times-Roman-Ogonki \
                -a ptmr-o.afm \
                -e ogonki.afm -t adobe.afm
@end example

@noindent
where @code{-i} specifies the AFM of the original font, @code{-c}
supplementary composite character information, @code{-o} the font
program to generate, @code{-n} the name of the new font, @code{-a} the
name of the AFM file to generate, @code{-e} the base encoding AFM to
use, and @code{-t} the target encoding.

The file @code{makecomp} contains a shell script (run by the
installation program) which generates fonts with composite characters
for the Times, Courier and Helvetica families from the supplementary
AFMs @code{*-c.afm}.

@node Composite example,  , Composite usage, Adding new characters
@section A step-by-step example

Assume that you want to add the @code{ccaron} and @code{Ccaron}
characters to the Times-Roman font.  Start from similar characters
already present in the base Times-Roman font --- for example,
@code{zcaron} and @code{Zcaron}.  Take the corresponding @dfn{composite
character} (@code{CC}) line from the @code{ptmr.afm} file:

@example
CC zcaron 2 ; PCC z 0 0 ; PCC caron 55 0 ;
@end example

@noindent
and insert it into the @code{ptmr-c.afm} file, changing the names
of the characters thus:

@example
CC ccaron 2 ; PCC c 0 0 ; PCC caron 55 0 ;
@end example

@noindent
This line can be used as a starting point.  Execute @code{./instogonki},
typeset some text with the new character, and fine-tune the last set of
coordinates (@code{55 0}).

If you create new AFMs or modify the existing ones, please send me a
copy so that I can include them in the distribution.

@node Reaching the author,  , Adding new characters, Top
@chapter Reaching the author

This manual and most of the Ogonkify package were written by Juliusz
Chroboczek, <jec@@dcs.ed.ac.uk>.

My current snail-mail address is:
@display
Juliusz Chroboczek
Department of Computer Science
Mayfield Road
Edinburgh EH9 3JZ
Scotland, United Kingdom
tel. +44/131/650-5163
fax. +44/131/667-7209
@end display

@c @contents
@bye
