summaryrefslogtreecommitdiff
path: root/Build/source/texk/afm2pl/afm2pl.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/afm2pl/afm2pl.xml')
-rw-r--r--Build/source/texk/afm2pl/afm2pl.xml598
1 files changed, 598 insertions, 0 deletions
diff --git a/Build/source/texk/afm2pl/afm2pl.xml b/Build/source/texk/afm2pl/afm2pl.xml
new file mode 100644
index 00000000000..54cf03e8bc1
--- /dev/null
+++ b/Build/source/texk/afm2pl/afm2pl.xml
@@ -0,0 +1,598 @@
+<?xml version='1.0' standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+ <!ENTITY szlig "&#x00DF;">
+]>
+<refentry>
+<refentryinfo>
+ <title>afm2pl</title>
+ <date>May 2009</date>
+</refentryinfo>
+
+<refmeta>
+ <refentrytitle>afm2pl</refentrytitle>
+ <manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+ <refname>afm2pl</refname>
+ <refpurpose>convert AFM font metrics to TeX pl font metrics
+ </refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+ <cmdsynopsis>
+ <command>afm2pl</command>
+ <arg choice="opt"><option>-p</option>
+ <replaceable>encoding_file</replaceable>
+ </arg>
+ <arg choice="opt"><option>-o</option></arg>
+ <arg choice="opt"><option>-e</option>
+ <replaceable>extension_factor</replaceable>
+ </arg>
+ <arg choice="opt"><option>-s</option>
+ <replaceable>slant_factor</replaceable>
+ </arg>
+ <arg choice="opt"><option>-f</option>
+ <replaceable>font_dimensions</replaceable>
+ </arg>
+ <arg choice="opt"><option>-k</option></arg>
+ <arg choice="opt"><option>-m</option>
+ <replaceable>letter_spacing</replaceable>
+ </arg>
+ <arg choice="opt"><option>-l</option>
+ <replaceable>ligkern_spec</replaceable>
+ </arg>
+ <arg choice="opt"><option>-L</option>
+ <replaceable>ligkern_spec</replaceable>
+ </arg>
+ <arg choice="opt"><option>-n</option></arg>
+ <arg choice="req"><replaceable>input_file[.afm]</replaceable></arg>
+ <arg choice="opt"><replaceable>output_file[.pl]</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>afm2pl</command>
+ <group choice="req">
+ <arg>--help</arg>
+ <arg>--version</arg>
+ </group>
+ </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+<para>afm2pl converts an afm (Adobe Font Metric) file into a pl
+(Property List) file, which in its turn can be converted to a tfm
+(TeX Font Metric) file. It normally preserves kerns and ligatures,
+but also offers additional control over them.</para>
+
+<para>afm2pl is meant to be a partial replacement for afm2tfm, on
+which it is based. With afm2tfm, preserving kerns and ligatures is
+possible only in a roundabout way, and handling of them is
+hard-wired.</para>
+
+<para>For text fonts, Y&amp;Y's texnansi is a good encoding to be
+used with afm2pl. Its character set includes all the accented
+characters likely to be needed for Western languages, plus many
+typographic symbols, without a need for either virtual fonts or a
+separate text companion font.</para>
+
+<para>Full LaTeX support for this encoding is available in the form
+of the texnansi package, which is already part of TeX Live and
+teTeX. These distributions also contain the encoding file
+texnansi.enc.</para>
+
+<para>The distribution contains uppercased and lowercased versions
+of texnansi, viz. texnanuc and texnanlc, to allow font-based rather
+than macro-based uppercasing and lowercasing, and the familiar old
+ot1 encoding plus some variations in PostScript .enc format (I
+included these because they seem to be absent from teTeX/TeX
+Live). However, <link linkend="mapwarn">check your mapfiles</link>
+if you have old afm2pl-generated fonts using these.</para>
+
+<para>Return value: 0 if no error; a negative number indicating the
+number of missing glyphs if conversion was otherwise successfull but
+glyphs are missing, and 1 in case of error.</para>
+</refsect1>
+
+<refsect1>
+<title>Options</title>
+<variablelist>
+<varlistentry>
+ <term><option>-p</option> <replaceable>encoding_file</replaceable></term>
+ <listitem>
+ <para>The default is the encoding specified in the afm file,
+ which had better match the encoding in the fontfile (pfa or
+ pfb). If <literal>afm2pl-name.enc</literal> exists, afm2pl will
+ use this file instead of <literal>name.enc</literal>, unless an
+ option <literal>-n</literal> is given. The generated mapfile
+ entry (see below) instructs pdftex or the dvi driver to
+ reencode the font on the fly. On-the-fly reencoding does not
+ require virtual fonts.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term><option>-o</option></term>
+ <listitem>
+ <para>Use octal for all character codes in the pl file.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term><option>-e</option> <replaceable>extend_factor</replaceable></term>
+ <listitem>
+ <para>Widen or narrow characters by
+ <replaceable>extend_factor</replaceable>. Default is 1.0
+ (natural width). Not recommended<footnote><para>Except that arguably a
+ narrowed Courier is less jarring than a full-width Courier,
+ when used in combination with a normal proportional font. For
+ Courier, choose .833 to match the width of cmtt. Better yet,
+ don't use Courier at all; most TeX distributions offer various
+ good replacements.</para></footnote>.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term><option>-s</option> <replaceable>slant_factor</replaceable></term>
+ <listitem>
+ <para>Oblique (slant) characters by
+ <replaceable>slant_factor</replaceable>.
+ Not recommended either.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term><option>-f</option>
+ <replaceable>font_dimensions</replaceable></term> <listitem>
+ <para>The value is either the
+ keyword <literal>afm2tfm</literal> or a comma-separated list of up
+ to five integers. The parameters are listed below, with their
+ defaults and their value when the afm2tfm keyword is
+ specified. &lsquo;Space&rsquo; means the width of a space in the
+ target font, except of course in the last row.
+ Keep in mind that the design size is 1000, and that all numbers
+ must be nonnegative integers.</para>
+
+<informaltable>
+<tgroup cols='3'>
+<colspec colwidth='*'/>
+<colspec colwidth='2*'/>
+<colspec colwidth='2*'/>
+<thead>
+<row>
+ <entry>Font dimension</entry>
+ <entry>Default value</entry>
+ <entry>Afm2tfm value</entry></row></thead>
+<tbody>
+
+<row>
+ <entry><replaceable>stretch</replaceable></entry>
+ <entry>space div 2</entry>
+ <entry>300 &times; <replaceable>extend_factor</replaceable></entry>
+</row>
+
+<row>
+<entry><replaceable>shrink</replaceable></entry>
+<entry>space div 3</entry>
+<entry>100 &times; <replaceable>extend_factor</replaceable></entry>
+</row>
+
+<row>
+ <entry><replaceable>extra space</replaceable></entry>
+ <entry>space div 3</entry>
+ <entry>missing</entry>
+</row>
+
+<row>
+ <entry><replaceable>quad</replaceable></entry>
+<entry>2 &times; width of &lsquo;0&rsquo;</entry>
+ <entry>1000 &times; <replaceable>extend_factor</replaceable></entry>
+</row>
+
+<row>
+ <entry><replaceable>space</replaceable></entry>
+ <entry>(space source font) &times; <replaceable>extend_factor</replaceable></entry>
+ <entry>(space source font) &times; <replaceable>extend_factor</replaceable></entry>
+</row>
+
+ </tbody></tgroup></informaltable>
+
+<para>For fixed-pitch fonts, different values apply:</para>
+
+<informaltable>
+<tgroup cols='3'>
+<colspec colwidth='*'/>
+<colspec colwidth='2*'/>
+<colspec colwidth='2*'/>
+<thead>
+<row>
+ <entry>Font dimension</entry>
+ <entry>Default value</entry>
+ <entry>Afm2tfm value</entry></row></thead>
+<tbody>
+
+<row>
+ <entry><replaceable>stretch</replaceable></entry>
+ <entry>0</entry>
+ <entry>0</entry>
+</row>
+
+<row>
+<entry><replaceable>shrink</replaceable></entry>
+ <entry>0</entry>
+ <entry>0</entry>
+</row>
+
+<row>
+ <entry><replaceable>extra space</replaceable></entry>
+ <entry>space</entry>
+ <entry>missing</entry>
+</row>
+
+<row>
+ <entry><replaceable>quad</replaceable></entry>
+<entry>2 &times; character width</entry>
+ <entry>1000 &times; <replaceable>extend_factor</replaceable></entry>
+</row>
+
+<row>
+ <entry><replaceable>space</replaceable></entry>
+ <entry>character width</entry>
+ <entry>character width</entry>
+</row>
+
+ </tbody></tgroup></informaltable>
+
+<para>Specify just a non-default stretch and shrink with
+ e.g. <literal>150,70</literal> and just a non-default extra
+ space with <literal>,,10</literal>.</para>
+
+ </listitem> </varlistentry>
+
+<varlistentry>
+ <term><option>-k</option></term>
+ <listitem>
+ <para>Keep original ligatures. This option only has effect in
+ combination with positive letterspacing; see the section on
+ <link linkend="lspace">letterspacing and extra ligkern info.</link>
+ </para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term><option>-m</option> <replaceable>letter_spacing</replaceable></term>
+ <listitem>
+ <para>Letterspace by
+ <replaceable>letter_spacing</replaceable>/1000 em
+ (integer). This is useful for making all-caps typesetting look
+ better. Try a value of e.g. 50 or 100. But see the section
+ on <link linkend="lspace">letterspacing and extra ligkern
+ info</link> for details. A better alternative, though, is
+ letting pdftex do the
+ letterspacing. The <package>microtype</package> package gives
+ LaTeX users access to this feature.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term><option>-l</option> <replaceable>ligkern_spec</replaceable></term>
+ <term><option>-L</option> <replaceable>ligkern_spec</replaceable></term>
+ <listitem>
+ <para> See the section
+ on <link linkend="lspecs">extra ligkern info</link>
+ for details.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term><option>-n</option></term>
+ <listitem>
+ <para>No prefix. For .enc- and .lig files, the program normally
+ first prefixes the name with `afm2pl-'. Only if the prefixed
+ filename is not found, will it search for the original
+ filename. This option prevents searching for the prefixed filename.
+ </para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term><option>-V</option></term>
+ <listitem>
+ <para>Verbose. If turned on, it reports the number of missing
+ glyphs to stderr and their names to stdout.
+ </para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term><option>--help</option></term>
+ <listitem>
+ <para>Display a short usage message.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display the version number of afm2pl.</para>
+ </listitem>
+</varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1>
+<title>Mapfile entries</title>
+<para>afm2pl writes a mapfile entry to a file with the same basename
+as the pl output file, but with extension .map. It can be used for
+the dvips mapfile and for the pdftex mapfile. It is assumed that the
+pfb file has the same basename as the afm file and must be
+downloaded. <emphasis>You may have to hand-edit this
+entry.</emphasis></para>
+
+<para>You can configure dvips and pdftex to read this additional
+mapfile or otherwise add the entry to an existing mapfile.</para>
+
+<para id="mapwarn"><emphasis role="strong">Check your
+ mapfiles!</emphasis> To reduce the likelihood of name conflicts,
+ the .enc- files which are part of afm2pl (ot1, ot1csc, ot1ital,
+ ot1tt, texnanlc and texnanuc) have now been prepended
+ with <literal>afm2pl-</literal>. The .enc files are referenced in
+ mapfiles. If you have old afm2pl-generated .tfm files using these,
+ then you should update their mapfile fragments and rerun updmap or
+ updmap-sys. Or you can copy the relevant enc files to your
+ personal or local texmf tree under their previous non-prefixed
+ names.</para>
+</refsect1>
+
+<refsect1 id="lspecs" xreflabel="ligkern specs">
+<title>Extra ligkern info</title>
+
+<para><emphasis>Most users are well-advised to leave this mess alone
+and to accept the default behavior.</emphasis></para>
+
+<para>The ligatures and kerns present in the afm file can be
+modified in various ways. Default, the encoding file is scanned for
+extra ligkern specifications, whose format will be described below.
+If there are no ligkern specifications in the encoding file, then
+extra ligkern specifications will be read from a file
+[afm2pl-]default.lig. A value of 0
+for <replaceable>ligkern_spec</replaceable> means that the ligatures
+and kerns from the afm file won't be tampered with and a value of 1
+specifies default behavior. One can also specify a comma-separated
+list of files with extra ligkerns specs.</para>
+
+<para>If afm2pl is compiled with the kpathsea library, then these
+files will be searched for under $TEXMF/fonts/lig.</para>
+
+<para><emphasis>Note that ligatures and kerns are hints for the
+typesetting application; there is no need to download this
+information to the printer or to make it available to a dvi
+driver.</emphasis></para>
+
+<para>The parser for ligkern info has been inherited from afm2tfm
+virtually without change. A ligkern specification can have one of
+the following forms:</para>
+
+<screen>
+<replaceable>glyph_name1</replaceable> <replaceable>glyph_name2</replaceable> <replaceable>lig_op</replaceable> <replaceable>glyph_name3</replaceable> ;
+</screen>
+
+<para>This specifies a ligature. Possible values for
+<replaceable>lig_op</replaceable> are <literal>=:</literal>,
+<literal>|=:</literal>, <literal>|=:></literal>,
+<literal>=:|</literal>, <literal>=:|></literal>,
+<literal>|=:|</literal>, <literal>|=:|></literal> and
+<literal>|=:|&gt;&gt;</literal>.
+These correspond to <literal>LIG</literal>,
+<literal>/LIG</literal>, <literal>/LIG&gt;</literal>,
+<literal>LIG/</literal>, <literal>LIG/&gt;</literal>,
+<literal>/LIG/</literal>, <literal>/LIG/&gt;</literal>,
+<literal>/LIG/&gt;&gt;</literal> in .pl syntax; see the pltotf
+documentation and the .lig files in the distribution.</para>
+
+<screen>
+<replaceable>glyph_name1</replaceable> &lt;&gt; <replaceable>glyph_name2</replaceable> ;
+</screen>
+
+<para>Kern <replaceable>glyph_name1</replaceable> as
+<replaceable>glyph_name2</replaceable>.</para>
+
+<screen>
+<replaceable>glyph_name1</replaceable> {} <replaceable>glyph_name2</replaceable> ;
+</screen>
+
+<para>Remove the kern between <replaceable>glyph_name1</replaceable>
+and <replaceable>glyph_name2</replaceable>. A value of
+<literal>*</literal> for either glyph name is interpreted as a
+wildcard.</para>
+
+<screen>
+|| = <replaceable>glyph</replaceable> ;
+</screen>
+
+<para>Set the (right) boundary character to
+<replaceable>glyph</replaceable>. <replaceable>glyph</replaceable>
+may be either a glyphname or a slot in the encoding vector. Choosing
+a glyph which doesn't occur in the output encoding is equivalent to
+not specifying a boundarychar at all. It is ok to pick an encoded
+glyphname which does not occur in the afm. In fact, this is what
+default.lig does: <literal>|| = cwm ;</literal>.</para>
+
+<para>You can copy the kerns of an unencoded character to the
+boundarychar. Below, <literal>space</literal> is the unencoded
+character:</para>
+
+<screen>
+|| &lt;&gt; space ;
+</screen>
+
+<para>This ligkern specification should occur before the one that
+deletes space kerns.</para>
+
+<para>A ligkern specification should be contained within one line.
+One line may contain several ligkern specifications, separated by
+spaces. Note that <literal> ;</literal> (space followed by
+semicolon) is considered part of the ligkern specification. See the
+lig files included in this distribution. Example:</para>
+
+<screen>
+one {} * ; * {} one ; two {} * ; * {} two ;
+</screen>
+
+<para>Lines with ligkern specifications inside an encoding file
+should start with <literal>% LIGKERN </literal>. Ligkern
+specifications in a lig file may optionally start this way.</para>
+</refsect1>
+
+<refsect1 id="lspace" xreflabel="letterspacing">
+<title>Letterspacing and extra ligkern info</title>
+
+<para>Letterspacing has various side-effects for ligkern
+info. Instead of simply applying the extra ligkern info (see
+previous section), the following is done:</para>
+
+<orderedlist>
+<listitem><para>In case of positive letterspacing, native ligatures
+are removed, unless the -k option is specified.</para></listitem>
+
+<listitem><para>Extra ligkern info is applied as usual, except that in
+case of positive letterspacing different defaults apply:
+<literal>-l 0</literal> is quietly ignored, ligkern comments in
+the encoding file are ignored, and defpre.lig is read instead of
+default.lig.</para></listitem>
+
+<listitem><para>Letterspacing is applied. This adds a lot of kerns,
+and modifies existing kerns.</para></listitem>
+
+<listitem><para>The extra ligkern info specified with -L is applied.
+The only ligkern specs which are allowed here, are removals of
+kerning pairs (with the <literal>{}</literal> operator). Values 0
+and 1 have a similar meaning as for the -l
+parameter. <emphasis id="lspacewarn">The tfm format has room for
+only about 180x180 ligatures and kerning pairs.</emphasis> This is
+enough for OT1 encoding, but for texnansi encoding quite a few
+ligkern specifications have to be removed. The pltotf program will
+remove <emphasis>all</emphasis> ligkern info if too many ligatures
+and kerns remain. The default lig file is defpost.lig. This file
+throws out kerning pairs which are unlikely to be involved in
+letterspacing, such as kerns involving accents or kerns with a
+punctuation character or right bracket at the left. It does not add
+letterspacing kerns involving boundarychars. Instead, fontspace is
+increased by twice the letterspacing. defpost.lig throws out enough
+kerns in case of texnansi encoding. With other encodings, you may
+have to throw out additional kerning
+pairs.</para></listitem> </orderedlist>
+</refsect1>
+
+<refsect1>
+<title>Font-based upper- and lowercasing</title>
+
+<para>The distribution includes encoding vectors texnanuc.enc and
+texnanlc.enc which produce all-uppercase and all-lowercase
+fonts</para>
+
+<para>The principal uses for an all-uppercase font are page headers
+and section heads. If these contain math, then macro-based
+uppercasing would create unpleasant complications. Example:
+<programlisting>
+afm2pl -p texnanuc ptmr8a ptmup8y
+pltotf ptmup8y
+</programlisting>
+For best results, you should add some letterspacing. In LaTeX, this
+is best done with the <package>microtype</package>
+package; see the documentation of that package. But it can also be
+done with <package>afm2pl</package>:
+<programlisting>
+afm2pl -p texnanuc -m 100 ptmr8a ptmup8y
+</programlisting>
+This requires caution;
+see <link linkend="lspacewarn">above.</link></para>
+
+<para>You can use this new font within the context of LaTeX font
+ selection as follows:
+<programlisting>
+<![CDATA[
+<preamble commands>
+\makeatletter
+{\nfss@catcodes
+\DeclareFontShape{LY1}{ptm}{m}{upp}{<-> ptmup8y}{}}
+\makeatother
+...
+\begin{document}
+...
+{\fontshape{upp}\selectfont uppercase text}
+]]>
+</programlisting>
+Note that <code>upp</code> is simply a newly made-up shape name.</para>
+
+<refsect2>
+<title>The sz ligature &szlig;</title>
+<para>Note that the texnanuc encoding provides no glyph for the sz
+ligature &szlig;; you'll either have to substitute ss or provide a
+macro-based solution. The following code uses either the usual glyph
+or substitutes the letters ss, depending on whether the glyph exists
+in the current font:</para>
+
+<programlisting>
+<![CDATA[
+\def\ss{%
+ \setbox0\hbox{\char25}%
+ \ifnum\wd0=0 ss\else\box0\fi
+}
+]]>
+</programlisting>
+<para>In LaTeX, this code appears to work well enough, although on
+occasion you may need to insert <literal>\protect</literal>. A
+better solution might involve the sixth parameter of the
+<literal>\DeclareFontShape</literal> macro, but I failed to get
+that to work.</para>
+</refsect2>
+</refsect1>
+
+<refsect1>
+<title>Afm2pl, fontinst and artificial smallcaps</title>
+
+<para>Afm2pl doesn't do virtual fonts. That means that for
+things such as artificial smallcaps you have to turn elsewhere,
+e.g. to the fontinst package, which is part of any mainstream TeX
+distribution.</para>
+
+<para>Look under texmf/tex/fontinst for fontinst support files,
+which allow you to generate a smallcaps font (tfm and vf files) from
+an afm2pl-generated tfm file. This package only supports texnansi
+encoding.</para>
+
+<para>There should be no real problem in doing the same for OT1
+encoding. However, there are several variations of the OT1 encoding
+to take care of. Also, there are as far as I know no officially
+sanctioned PostScript names for all the variations of the OT1
+encoding; the fontinst names contain spaces and are therefore not
+useable as PostScript names.</para>
+</refsect1>
+
+<refsect1>
+<title>Changed in version 0.7.1</title>
+
+<para>In order to avoid name conflicts, the .enc- and .lig files
+ distributed with afm2pl got <literal>afm2pl-</literal> prepended
+ to their name. The program itself now first searches for the thus
+ prepended name. If the .enc- or .lig file is not found it will
+ look for the original filename. The renaming of the afm2pl .enc
+ files may require modification of some mapfiles.</para>
+</refsect1>
+
+<refsect1><title>Urls</title>
+<para>The afm2pl homepage is <ulink
+url="http://tex.aanhet.net/afm2pl/">http://tex.aanhet.net/afm2pl/</ulink>.</para>
+
+<para>The paper
+ <ulink url="http://www.tug.org/TUGboat/Articles/tb27-1/tb86kroonenberg-fonts.pdf">Font
+ installation the shallow way</ulink> (EuroTeX 2006 Proceedings,
+ published
+ as <ulink url="http://www.tug.org/TUGboat/">TUGboat</ulink> issue
+ 27.1) illustrates the use of afm2pl.</para>
+</refsect1>
+
+</refentry>