diff options
Diffstat (limited to 'Build/source/texk/afm2pl/afm2pl.xml')
-rw-r--r-- | Build/source/texk/afm2pl/afm2pl.xml | 598 |
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 "ß"> +]> +<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&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. ‘Space’ 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 × <replaceable>extend_factor</replaceable></entry> +</row> + +<row> +<entry><replaceable>shrink</replaceable></entry> +<entry>space div 3</entry> +<entry>100 × <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 × width of ‘0’</entry> + <entry>1000 × <replaceable>extend_factor</replaceable></entry> +</row> + +<row> + <entry><replaceable>space</replaceable></entry> + <entry>(space source font) × <replaceable>extend_factor</replaceable></entry> + <entry>(space source font) × <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 × character width</entry> + <entry>1000 × <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>|=:|>></literal>. +These correspond to <literal>LIG</literal>, +<literal>/LIG</literal>, <literal>/LIG></literal>, +<literal>LIG/</literal>, <literal>LIG/></literal>, +<literal>/LIG/</literal>, <literal>/LIG/></literal>, +<literal>/LIG/>></literal> in .pl syntax; see the pltotf +documentation and the .lig files in the distribution.</para> + +<screen> +<replaceable>glyph_name1</replaceable> <> <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> +|| <> 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 ß</title> +<para>Note that the texnanuc encoding provides no glyph for the sz +ligature ß; 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> |