afm2pl update; sources

git-svn-id: svn://tug.org/texlive/trunk@13850 c570f23f-e606-0410-a88d-b1316a301751

8 files changed, 681 insertions, 334 deletions

diff --git a/Build/source/texk/afm2pl/ChangeLog b/Build/source/texk/afm2pl/ChangeLog
index db3dbe2a727..4e0b2448b09 100644
--- a/Build/source/texk/afm2pl/ChangeLog
+++ b/Build/source/texk/afm2pl/ChangeLog
@@ -1,3 +1,17 @@
+2009-06-21  Siep Kroonenberg  <siepo@cybercomm.nl>
+
+	* Makefile.am: remove references to afm2pl.[txt|html]
+	* Makefile.in: regenerated
+	* afm2pl.c:
+	(openin): find afm2pl-<name>.[lig|enc] before <name>.[lig|enc]
+	* afm2pl.[1|xml]: updated
+	* afm2pl.[html|txt]: removed
+	* README: updated
+	* README.DOC (new): describes generation of afm2pl.1 and afm2pl.pdf
+	from afm2pl.xml
+	* Support files in texmf: corrected ot1tt.enc, added
+	prefix to enc files, pre-generated afm2pl.pdf; see also svn logs
+
 2009-06-13  Peter Breitenlohner  <peb@mppmu.mpg.de>
 
 	* Makefile.am (AM_CFLAGS): enable compiler warnings.
diff --git a/Build/source/texk/afm2pl/Makefile.am b/Build/source/texk/afm2pl/Makefile.am
index e51e4b887b7..0306b03cdcb 100644
--- a/Build/source/texk/afm2pl/Makefile.am
+++ b/Build/source/texk/afm2pl/Makefile.am
@@ -15,7 +15,7 @@ afm2pl_SOURCES = afm2pl.c
 
 afm2pl_DEPENDENCIES = $(KPATHSEA_DEPEND)
 
-LDADD = $(KPATHSEA_LIBS)	
+LDADD = $(KPATHSEA_LIBS)
 
 ## Rebuild libkpathsea
 @KPATHSEA_RULE@
@@ -24,14 +24,12 @@ dist_man1_MANS = afm2pl.1
 
 TESTS = afm2pl.test
 
-EXTRA_DIST = afm2pl.test logo10.afm xlogo10.map xlogo10.pl 
+EXTRA_DIST = afm2pl.test logo10.afm xlogo10.map xlogo10.pl
 
 CLEANFILES = logo10.map logo10.pl
 
 ## Not used
 ##
 EXTRA_DIST += \
-	afm2pl.html \
-	afm2pl.txt \
-	afm2pl.xml
+	afm2pl.xml README.DOC
 
diff --git a/Build/source/texk/afm2pl/Makefile.in b/Build/source/texk/afm2pl/Makefile.in
index a0485cf4400..ae442d525a2 100644
--- a/Build/source/texk/afm2pl/Makefile.in
+++ b/Build/source/texk/afm2pl/Makefile.in
@@ -250,11 +250,11 @@ AM_CPPFLAGS = -DKPATHSEA
 AM_CFLAGS = $(WARNING_CFLAGS)
 afm2pl_SOURCES = afm2pl.c
 afm2pl_DEPENDENCIES = $(KPATHSEA_DEPEND)
-LDADD = $(KPATHSEA_LIBS)	
+LDADD = $(KPATHSEA_LIBS)
 dist_man1_MANS = afm2pl.1
 TESTS = afm2pl.test
-EXTRA_DIST = afm2pl.test logo10.afm xlogo10.map xlogo10.pl afm2pl.html \
-	afm2pl.txt afm2pl.xml
+EXTRA_DIST = afm2pl.test logo10.afm xlogo10.map xlogo10.pl afm2pl.xml \
+	README.DOC
 CLEANFILES = logo10.map logo10.pl
 all: c-auto.h
 	$(MAKE) $(AM_MAKEFLAGS) all-am
diff --git a/Build/source/texk/afm2pl/README b/Build/source/texk/afm2pl/README
index 14526949fad..d4fb72b144e 100644
--- a/Build/source/texk/afm2pl/README
+++ b/Build/source/texk/afm2pl/README
@@ -1,9 +1,10 @@
 DESCRIPTION
 
-afm2pl is meant to be a replacement for afm2tfm, on which it is
-based. Its default action is to convert an afm file to a tfm file,
-with preservation of kerns and ligatures (with afm2tfm, preserving
-kerns and ligatures is possible only in a roundabout way).
+afm2pl is meant to be a partial replacement for afm2tfm, on which it
+is based. Its default action is to convert an afm file to a tfm
+file, with preservation of kerns and ligatures (with afm2tfm,
+preserving kerns and ligatures is possible only in a roundabout
+way).
 
 For PostScript text fonts, Y&Y's texnansi is the recommended
 encoding to be used with afm2pl.  This gives you a good character
@@ -15,10 +16,11 @@ Full LaTeX support for this encoding is available in the form of the
 texnansi package, which is already part of TeX Live and teTeX.
 
 The distribution also contains uppercased and lowercased versions of
-texnansi, texnanuc.enc and texnanlc.enc, to allow font-based rather
-than macro-based uppercasing and lowercasing. LaTeX macro support
-for this, in the context of LaTeX2e's font handling, is not hard;
-the key is to treat all-uppercase and all-lowercase as new shapes.
+texnansi, [afm2pl-]texnanuc.enc and [afm2pl-]texnanlc.enc, to allow
+font-based rather than macro-based uppercasing and
+lowercasing. LaTeX macro support for this, in the context of
+LaTeX2e's font handling, is not hard; the key is to treat
+all-uppercase and all-lowercase as new shapes.
 
 USAGE
 
@@ -32,6 +34,7 @@ This is the help message printed by afm2pl:
   -e REAL             Widen (extend) characters by a factor of REAL
   -s REAL             Oblique (slant) characters by REAL, generally <<1
   -m INTEGER          Letterspace by INTEGER/1000 em
+  -V                  Verbose output; i.e. report on missing glyphs
   --help              Print this message and exit.
   --version           Print version number and exit.
 
@@ -43,13 +46,22 @@ This is the help message printed by afm2pl:
 
 INSTALLATION FROM SOURCE
 
-Afm2pl is meant to be incorporated into a current TeX Live/teTeX
-installation. TeX Live already includes afm2pl, and for teTeX
-(version >= 3.0) you can simply place the afm2pl source directory
-under texk before compilation. A Windows binary is also provided.
+Afm2pl is part of the TeX Live source tree. Standalone compilation
+may still work, but is no longer supported.
 
 TROUBLESHOOTING
 
+Problem: the fonts appear to be missing or I get the wrong characters.
+
+Solution: check your mapfiles. Starting TeX Live 2009, the
+afm2pl-specific .enc files got `afm2pl-' prepended to their
+names. Although you don't have to add this prefix to the
+command-line, the prefix is necessary in the mapfile. You may have
+to edit your mapfiles accordingly.
+
+Also, afm2pl-ot1tt.enc is brought in conformance with the monospaced
+version of OT1, and ot1csc.enc has been removed altogether.
+
 Problem: I get warnings
 
   I had to round some heights by 10.0000000 units.
@@ -76,10 +88,10 @@ contains all kerning pairs which are likely to matter. If you use a
 different encoding, you might exceed these boundaries and as a
 consequence lose all glyphs and kerns.
 
-Feedback is welcome.
+Consider using the tracking option of the microtype package instead.
 
-June 23 2005
+June 21 2009
 
 Siep Kroonenberg
 ntg-afm2pl@ntg.nl
-http://www.ntg.nl/afm2pl.html
+http://tex.aanhet.net/afm2pl/
diff --git a/Build/source/texk/afm2pl/README.DOCS b/Build/source/texk/afm2pl/README.DOCS
new file mode 100644
index 00000000000..2eba5e78c72
--- /dev/null
+++ b/Build/source/texk/afm2pl/README.DOCS
@@ -0,0 +1,77 @@
+GENERATING THE DOCUMENTATION
+
+The documentation source is a DocBook refentry. Texinfo would have
+made more sense, but at the time it was a nice excuse to have a look
+at DocBook, xml and xslt.
+
+The manpage and pdf were generated separately, not as part of the
+TeX Live build process.
+
+The required tools, dblatex and xmlto, are available as Ubuntu- and
+Debian packages.
+
+The pdf is generated with dblatex, with a command-line
+
+dblatex -P latex.hyperparam=bookmarks=false,colorlinks \
+  -s ./mystyle.sty \
+  -p ./dbl.xsl \
+  afm2pl.xml
+
+This is the contents of mystyle.sty:
+
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{mystyle}
+\RequirePackageWithOptions{db2latex}
+\AtBeginDocument{\setcounter{secnumdepth}{-1}}
+
+This is the contents of dbl.xsl:
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version='1.0'>
+
+<xsl:variable name="arg.choice.opt.open.str"><xsl:text> [</xsl:text></xsl:variable>
+<xsl:variable name="arg.choice.opt.close.str"><xsl:text>] </xsl:text></xsl:variable>
+<xsl:variable name="arg.choice.req.open.str"><xsl:text> {</xsl:text></xsl:variable>
+<xsl:variable name="arg.choice.req.close.str"><xsl:text>} </xsl:text></xsl:variable>
+<xsl:variable name="arg.choice.def.open.str"><xsl:text> [</xsl:text></xsl:variable>
+<xsl:variable name="arg.choice.def.close.str"><xsl:text>] </xsl:text></xsl:variable>
+
+<xsl:template match="cmdsynopsis">
+  <xsl:text>{\raggedright\parindent0pt\parskip7pt &#10;</xsl:text>
+  <xsl:call-template name="label.id"/>
+  <xsl:apply-templates/>
+  <xsl:text>&#10; \par}</xsl:text>
+</xsl:template>
+
+<xsl:param name="monoseq.hyphenation">0</xsl:param>
+<xsl:template match="synopsis">
+  <xsl:call-template name="label.id"/>
+  <xsl:call-template name="output.verbatim"/>
+</xsl:template>
+<xsl:template match="option">
+  <xsl:call-template name="inline.monoseq"/><xsl:text> </xsl:text>
+</xsl:template>
+</xsl:stylesheet>
+
+The manpage is generated with xmlto, which uses xsltproc and docbook
+xsl transformations. The command-line is:
+
+  xmlto -m xml2.xsl man afm2pl.xml
+
+This is the contents of xml2.xsl:
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+<xsl:variable name="arg.choice.req.open.str"></xsl:variable>
+<xsl:variable name="arg.choice.req.close.str"></xsl:variable>
+<xsl:template name="make.toc"></xsl:template>
+</xsl:stylesheet>
+
+An html version can be generated with
+
+xmlto -m xml2.xsl html-nochunks afm2pl.xml
+
+June 21 2009
+
+Siep Kroonenberg
+ntg-afm2pl@ntg.nl
+http://tex.aanhet.net/afm2pl/
diff --git a/Build/source/texk/afm2pl/afm2pl.1 b/Build/source/texk/afm2pl/afm2pl.1
index 91c8282166d..272e27754c4 100644
--- a/Build/source/texk/afm2pl/afm2pl.1
+++ b/Build/source/texk/afm2pl/afm2pl.1
@@ -1,275 +1,464 @@
-.\"Generated by db2man.xsl. Don't modify this, modify the source.
-.de Sh \" Subsection
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Ip \" List item
-.br
-.ie \\n(.$>=3 .ne \\$3
-.el .ne 3
-.IP "\\$1" \\$2
-..
-.TH "AFM2PL" 1 "February 2004" "" "afm2pl"
-.SH NAME
+.\"     Title: afm2pl
+.\"    Author: 
+.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
+.\"      Date: May 2009
+.\"    Manual: afm2pl
+.\"    Source: 
+.\"
+.TH "AFM2PL" "1" "May 2009" "" "afm2pl"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
 afm2pl \- convert AFM font metrics to TeX pl font metrics
 .SH "SYNOPSIS"
-.ad l
-.hy 0
 .HP 7
-\fBafm2pl\fR [\fB\-p\fR\ \fIencoding_file\fR] [\fB\-o\fR] [\fB\-e\fR\ \fIextension_factor\fR] [\fB\-s\fR\ \fIslant_factor\fR] [\fB\-f\fR\ \fIfont_dimensions\fR] [\fB\-k\fR] [\fB\-m\fR\ \fIletter_spacing\fR] [\fB\-l\fR\ \fIligkern_spec\fR] [\fB\-L\fR\ \fIligkern_spec\fR] {\fIinput_file[\&.afm]\fR} [\fIoutput_file[\&.pl]\fR]
-.ad
-.hy
-.ad l
-.hy 0
+\fBafm2pl\fR [\fB\-p\fR\ \fIencoding_file\fR] [\fB\-o\fR] [\fB\-e\fR\ \fIextension_factor\fR] [\fB\-s\fR\ \fIslant_factor\fR] [\fB\-f\fR\ \fIfont_dimensions\fR] [\fB\-k\fR] [\fB\-m\fR\ \fIletter_spacing\fR] [\fB\-l\fR\ \fIligkern_spec\fR] [\fB\-L\fR\ \fIligkern_spec\fR] [\fB\-n\fR] \fIinput_file[\&.afm]\fR [\fIoutput_file[\&.pl]\fR]
 .HP 7
-\fBafm2pl\fR {\fB\-\-help\fR | \fB\-\-version\fR}
-.ad
-.hy
-
+\fBafm2pl\fR [\-\-help] | [\-\-version]
 .SH "DESCRIPTION"
-
 .PP
-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 preserves kerns and ligatures\&.
-
+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\&.
 .PP
-afm2pl is meant to be a replacement for afm2tfm, on which it is based\&. With afm2tfm, preserving kerns and ligatures is possible only in a roundabout way\&.
-
+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\&.
 .PP
-For text fonts, Y&Y's texnansi is the recommended encoding to be used with afm2pl\&. This gives you a good character set with all the more important accented characters and many typographic symbols available as single characters, without a need for either virtual fonts or a separate text companion font\&.
-
+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\&.
 .PP
 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\&.
-
 .PP
-The distribution contains uppercased and lowercased versions of texnansi, viz\&. texnanuc\&.enc and texnanlc\&.enc, 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)\&.
-
+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,
+check your mapfiles
+if you have old afm2pl\-generated fonts using these\&.
 .PP
-Return value: 0 if no error; a negative number indicating the number of missing glyphs if conversion was successfull but glyphs are missing, and 1 in case of error\&.
-
+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\&.
 .SH "OPTIONS"
-
-.TP
+.PP
 \fB\-p\fR \fIencoding_file\fR
-The default is the encoding specified in the afm file, which had better match the encoding in the fontfile (pfa or pfb)\&. 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\&.
-
-.TP
+.RS 4
+The default is the encoding specified in the afm file, which had better match the encoding in the fontfile (pfa or pfb)\&. If
+afm2pl\-name\&.enc
+exists, afm2pl will use this file instead of
+name\&.enc, unless an option
+\-n
+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\&.
+.RE
+.PP
 \fB\-o\fR
+.RS 4
 Use octal for all character codes in the pl file\&.
-
-.TP
+.RE
+.PP
 \fB\-e\fR \fIextend_factor\fR
-Widen or narrow characters by \fIextend_factor\fR\&. Default is 1\&.0 (natural width)\&. Not recommended, 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\&.
-
-.TP
+.RS 4
+Widen or narrow characters by
+\fIextend_factor\fR\&. Default is 1\&.0 (natural width)\&. Not recommended\&[1]\&.
+.RE
+.PP
 \fB\-s\fR \fIslant_factor\fR
-Oblique (slant) characters by \fIslant_factor\fR\&. Not recommended\&.
-
-.TP
-\fB\-f\fR \fIfont_dimensions\fR
-The value is either the keyword afm2tfm 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\&.
-
+.RS 4
+Oblique (slant) characters by
+\fIslant_factor\fR\&. Not recommended either\&.
+.RE
 .PP
+\fB\-f\fR \fIfont_dimensions\fR
+.RS 4
+The value is either the keyword
+afm2tfm
+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\&. \(oqSpace\(cq 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\&.
 .TS
-lll
-___
-lll.
-Font dimension	Default value	Afm2tfm value
-\fIstretch\fR	space div 2	300 x \fIextend_factor\fR
-\fIshrink\fR	space div 3	100 x \fIextend_factor\fR
-\fIextra space\fR	space div 3	missing
-\fIquad\fR	2 x width of '0'	1000 x \fIextend_factor\fR
-\fIspace\fR	(space source font) x \fIextend_factor\fR	(space source font) x \fIextend_factor\fR
+allbox tab(:);
+lB lB lB.
+T{
+Font dimension
+T}:T{
+Default value
+T}:T{
+Afm2tfm value
+T}
+.T&
+l l l
+l l l
+l l l
+l l l
+l l l.
+T{
+\fIstretch\fR
+T}:T{
+space div 2
+T}:T{
+300 \(mu \fIextend_factor\fR
+T}
+T{
+\fIshrink\fR
+T}:T{
+space div 3
+T}:T{
+100 \(mu \fIextend_factor\fR
+T}
+T{
+\fIextra space\fR
+T}:T{
+space div 3
+T}:T{
+missing
+T}
+T{
+\fIquad\fR
+T}:T{
+2 \(mu width of \(oq0\(cq
+T}:T{
+1000 \(mu \fIextend_factor\fR
+T}
+T{
+\fIspace\fR
+T}:T{
+(space source font) \(mu \fIextend_factor\fR
+T}:T{
+(space source font) \(mu \fIextend_factor\fR
+T}
 .TE
+.sp
 For fixed\-pitch fonts, different values apply:
-
-.PP
 .TS
-lll
-___
-lll.
-Font dimension	Default value	Afm2tfm value
-\fIstretch\fR	0	0
-\fIshrink\fR	0	0
-\fIextra space\fR	space	missing
-\fIquad\fR	2 x character width	1000 x \fIextend_factor\fR
-\fIspace\fR	character width	character width
+allbox tab(:);
+lB lB lB.
+T{
+Font dimension
+T}:T{
+Default value
+T}:T{
+Afm2tfm value
+T}
+.T&
+l l l
+l l l
+l l l
+l l l
+l l l.
+T{
+\fIstretch\fR
+T}:T{
+0
+T}:T{
+0
+T}
+T{
+\fIshrink\fR
+T}:T{
+0
+T}:T{
+0
+T}
+T{
+\fIextra space\fR
+T}:T{
+space
+T}:T{
+missing
+T}
+T{
+\fIquad\fR
+T}:T{
+2 \(mu character width
+T}:T{
+1000 \(mu \fIextend_factor\fR
+T}
+T{
+\fIspace\fR
+T}:T{
+character width
+T}:T{
+character width
+T}
 .TE
-Specify just a non\-default stretch and shrink with e\&.g\&. 150,70 and just a non\-default extra space with ,,10\&.
-
-.TP
+.sp
+Specify just a non\-default stretch and shrink with e\&.g\&.
+150,70
+and just a non\-default extra space with
+,,10\&.
+.RE
+.PP
 \fB\-k\fR
-Keep original ligatures\&. This option only has effect in combination with positive letterspacing; see the section on letterspacing and extra ligkern info\&. 
-
-.TP
+.RS 4
+Keep original ligatures\&. This option only has effect in combination with positive letterspacing; see the section on
+letterspacing and extra ligkern info\&.
+.RE
+.PP
 \fB\-m\fR \fIletter_spacing\fR
-Letterspace by \fIletter_spacing\fR/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 letterspacing and extra ligkern info for details\&.
-
-.TP
+.RS 4
+Letterspace by
+\fIletter_spacing\fR/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
+letterspacing and extra ligkern info
+for details\&. A better alternative, though, is letting pdftex do the letterspacing\&. The
+microtype
+package gives LaTeX users access to this feature\&.
+.RE
+.PP
 \fB\-l\fR \fIligkern_spec\fR, \fB\-L\fR \fIligkern_spec\fR
-See the section on extra ligkern info for details\&.
-
-.TP
+.RS 4
+See the section on
+extra ligkern info
+for details\&.
+.RE
+.PP
+\fB\-n\fR
+.RS 4
+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\&.
+.RE
+.PP
 \fB\-V\fR
-Verbose\&. If turned on, it reports the number of missing glyphs to stderr and their names to stdout\&. This is not particularly logical, but this way the glyph names can be captured even under Windows\&.
-
-.TP
+.RS 4
+Verbose\&. If turned on, it reports the number of missing glyphs to stderr and their names to stdout\&.
+.RE
+.PP
 \fB\-\-help\fR
+.RS 4
 Display a short usage message\&.
-
-.TP
+.RE
+.PP
 \fB\-\-version\fR
+.RS 4
 Display the version number of afm2pl\&.
-
+.RE
 .SH "MAPFILE ENTRIES"
-
 .PP
-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, although, in case of a geometrically transformed font, it may be better to remove the PostScript name for a pdftex mapfile entry\&. It is assumed that the pfb file has the same basename as the afm file and must be downloaded\&. You may have to hand\-edit this entry\&.
-
+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\&.
+\fIYou may have to hand\-edit this entry\&.\fR
 .PP
-You can configure dvips and pdftex to read this additional mapfile or otherwise add the entry to an existing mapfile\&. It appears that pdftex automatically will consult a mapfile xxx\&.map for a font xxx\&.
-
+You can configure dvips and pdftex to read this additional mapfile or otherwise add the entry to an existing mapfile\&.
+.PP
+\fBCheck your mapfiles!\fR
+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
+afm2pl\-\&. 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\&.
 .SH "EXTRA LIGKERN INFO"
-
 .PP
-Most users are well\-advised to leave this mess alone and to accept the default behavior\&.
-
+\fIMost users are well\-advised to leave this mess alone and to accept the default behavior\&.\fR
 .PP
-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 default\&.lig\&. A value of 0 for \fIligkern_spec\fR 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\&.
-
+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
+\fIligkern_spec\fR
+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\&.
 .PP
 If afm2pl is compiled with the kpathsea library, then these files will be searched for under $TEXMF/fonts/lig\&.
-
 .PP
-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\&.
-
+\fINote 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\&.\fR
 .PP
 The parser for ligkern info has been inherited from afm2tfm virtually without change\&. A ligkern specification can have one of the following forms:
-
-.IP
-
+.sp
+.RS 4
+.nf
 \fIglyph_name1\fR \fIglyph_name2\fR \fIlig_op\fR \fIglyph_name3\fR ;
-
-.PP
-This specifies a ligature\&. Possible values for \fIlig_op\fR are =:, |=:, |=:>, =:|, =:|>, |=:|, |=:|> and |=:|>>\&. These correspond to LIG, /LIG, /LIG>, LIG/, LIG/>, /LIG/, /LIG/>, /LIG/>> in \&.pl syntax; see the pltotf documentation and the \&.lig files in the distribution\&.
-
-.IP
-
+.fi
+.RE
+.PP
+This specifies a ligature\&. Possible values for
+\fIlig_op\fR
+are
+=:,
+|=:,
+|=:>,
+=:|,
+=:|>,
+|=:|,
+|=:|>
+and
+|=:|>>\&. These correspond to
+LIG,
+/LIG,
+/LIG>,
+LIG/,
+LIG/>,
+/LIG/,
+/LIG/>,
+/LIG/>>
+in \&.pl syntax; see the pltotf documentation and the \&.lig files in the distribution\&.
+.sp
+.RS 4
+.nf
 \fIglyph_name1\fR <> \fIglyph_name2\fR ;
-
-.PP
-Kern \fIglyph_name1\fR as \fIglyph_name2\fR\&.
-
-.IP
-
+.fi
+.RE
+.PP
+Kern
+\fIglyph_name1\fR
+as
+\fIglyph_name2\fR\&.
+.sp
+.RS 4
+.nf
 \fIglyph_name1\fR {} \fIglyph_name2\fR ;
-
-.PP
-Remove the kern between \fIglyph_name1\fR and \fIglyph_name2\fR\&. A value of * for either glyph name is interpreted as a wildcard\&.
-
-.IP
-
+.fi
+.RE
+.PP
+Remove the kern between
+\fIglyph_name1\fR
+and
+\fIglyph_name2\fR\&. A value of
+*
+for either glyph name is interpreted as a wildcard\&.
+.sp
+.RS 4
+.nf
 || = \fIglyph\fR ;
-
-.PP
-Set the (right) boundary character to \fIglyph\fR\&. \fIglyph\fR 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: || = cwm ;\&.
-
-.PP
-You can copy the kerns of an unencoded character to the boundarychar:
-
-.IP
-
+.fi
+.RE
+.PP
+Set the (right) boundary character to
+\fIglyph\fR\&.
+\fIglyph\fR
+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:
+|| = cwm ;\&.
+.PP
+You can copy the kerns of an unencoded character to the boundarychar\&. Below,
+space
+is the unencoded character:
+.sp
+.RS 4
+.nf
 || <> space ;
-
+.fi
+.RE
 .PP
 This ligkern specification should occur before the one that deletes space kerns\&.
-
 .PP
-A ligkern specification should be contained within one line\&. One line may contain several ligkern specifications, separated by spaces\&. Note that ; (space followed by semicolon) is considered part of the ligkern specification\&. See the lig files included in this distribution\&. Example:
-
-.IP
-
+A ligkern specification should be contained within one line\&. One line may contain several ligkern specifications, separated by spaces\&. Note that
+;
+(space followed by semicolon) is considered part of the ligkern specification\&. See the lig files included in this distribution\&. Example:
+.sp
+.RS 4
+.nf
 one {} * ; * {} one ; two {} * ; * {} two ;
-
+.fi
+.RE
 .PP
-Lines with ligkern specifications inside an encoding file should start with % LIGKERN\&. Ligkern specifications in a lig file may optionally start this way\&.
-
+Lines with ligkern specifications inside an encoding file should start with
+% LIGKERN\&. Ligkern specifications in a lig file may optionally start this way\&.
 .SH "LETTERSPACING AND EXTRA LIGKERN INFO"
-
 .PP
 Letterspacing has various side\-effects for ligkern info\&. Instead of simply applying the extra ligkern info (see previous section), the following is done:
-
-.TP 3
-1.
-In case of positive letterspacing, native ligatures are removed, unless the \-k option is specified\&.
-.TP
-2.
-Extra ligkern info is applied as usual, except that in case of positive letterspacing different defaults apply: \-l 0 is quietly ignored, ligkern comments in the encoding file are ignored, and defpre\&.lig is read instead of default\&.lig\&.
-.TP
-3.
-Letterspacing is applied\&. This adds a lot of kerns, and modifies existing kerns\&.
-.TP
-4.
-The extra ligkern info specified with \-L is applied\&. The only ligkern specs which are allowed here, are removals of kerning pairs (with the {} operator)\&. Values 0 and 1 have a similar meaning as for the \-l parameter\&. The tfm format has room for only about 180x180 ligatures and kerning pairs\&. This is enough for OT1 encoding, but for texnansi encoding quite a few ligkern specifications have to be removed\&. The pltotf program will remove all 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\&.
-.LP
-
+.sp
+.RS 4
+\h'-04' 1.\h'+02'In case of positive letterspacing, native ligatures are removed, unless the \-k option is specified\&.
+.RE
+.sp
+.RS 4
+\h'-04' 2.\h'+02'Extra ligkern info is applied as usual, except that in case of positive letterspacing different defaults apply:
+\-l 0
+is quietly ignored, ligkern comments in the encoding file are ignored, and defpre\&.lig is read instead of default\&.lig\&.
+.RE
+.sp
+.RS 4
+\h'-04' 3.\h'+02'Letterspacing is applied\&. This adds a lot of kerns, and modifies existing kerns\&.
+.RE
+.sp
+.RS 4
+\h'-04' 4.\h'+02'The extra ligkern info specified with \-L is applied\&. The only ligkern specs which are allowed here, are removals of kerning pairs (with the
+{}
+operator)\&. Values 0 and 1 have a similar meaning as for the \-l parameter\&.
+\fIThe tfm format has room for only about 180x180 ligatures and kerning pairs\&.\fR
+This is enough for OT1 encoding, but for texnansi encoding quite a few ligkern specifications have to be removed\&. The pltotf program will remove
+\fIall\fR
+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\&.
+.RE
 .SH "FONT-BASED UPPER- AND LOWERCASING"
-
 .PP
-The distribution includes encoding vectors texnanuc\&.enc and texnanlc\&.enc which produce all\-uppercase and all\-lowercase fonts\&. The distribution contains an example ucshape\&.tex on how to use such fonts with LaTeX font selection\&.
-
+The distribution includes encoding vectors texnanuc\&.enc and texnanlc\&.enc which produce all\-uppercase and all\-lowercase fonts
 .PP
-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\&.
-
-.SS "The sz ligature"
+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:
+.sp
+.RS 4
+.nf
+afm2pl \-p texnanuc ptmr8a ptmup8y
+pltotf ptmup8y
+.fi
+.RE
+.sp
+For best results, you should add some letterspacing\&. In LaTeX, this is best done with the
+microtype
+package; see the documentation of that package\&. But it can also be done with
+afm2pl:
+.sp
+.RS 4
+.nf
+afm2pl \-p texnanuc \-m 100 ptmr8a ptmup8y
+.fi
+.RE
+.sp
+This requires caution; see
+above\&.
+.PP
+You can use this new font within the context of LaTeX font selection as follows:
+.sp
+.RS 4
+.nf
 
-.PP
-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:
+<preamble commands>
+\emakeatletter
+{\enfss@catcodes
+\eDeclareFontShape{LY1}{ptm}{m}{upp}{<\-> ptmup8y}{}}
+\emakeatother
+\&.\&.\&.
+\ebegin{document}
+\&.\&.\&.
+{\efontshape{upp}\eselectfont uppercase text}
 
+.fi
+.RE
+.sp
+Note that
+upp
+is simply a newly made\-up shape name\&.
+.SS "The sz ligature \(ss"
+.PP
+Note that the texnanuc encoding provides no glyph for the sz ligature \(ss; 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:
+.sp
+.RS 4
 .nf
 
-
-\\def\\ss{%
-  \\setbox0\\hbox{\\char25}%
-  \\ifnum\\wd0=0 ss\\else\\box0\\fi
+\edef\ess{%
+  \esetbox0\ehbox{\echar25}%
+  \eifnum\ewd0=0 ss\eelse\ebox0\efi
 }
 
-
 .fi
-
+.RE
 .PP
-In LaTeX, this code appears to work well enough, although on occasion you may need to insert \\protect\&. A better solution might involve the sixth parameter of the \\DeclareFontShape macro, but I failed to get that to work\&.
-
+In LaTeX, this code appears to work well enough, although on occasion you may need to insert
+\eprotect\&. A better solution might involve the sixth parameter of the
+\eDeclareFontShape
+macro, but I failed to get that to work\&.
 .SH "AFM2PL, FONTINST AND ARTIFICIAL SMALLCAPS"
-
 .PP
-Afm2pl currently 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\&.
-
+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\&.
 .PP
 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\&.
-
 .PP
 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\&.
-
-.SH "FUTURE PLANS"
-
-.PP
-I am considering a revision which makes afm2pl a more complete replacement for afm2tfm\&. In that version, afm2pl can optionally create a second, virtual font, possibly with a different encoding and possibly letterspaced\&. The current option of non\-virtual letterspacing via kerns will be dropped\&. If the encodings differ then it is assumed that the virtual font is intended as a small\-caps version of the main font, and a scaling parameter can be specified for non\-matching glyphs\&.
-
-.SH "COPYRIGHT"
-
-.PP
-The afm2pl distribution is subject to the GNU General Public Licence (GPL)\&. Please refer to the file COPYING for details\&.
-
-.PP
-The afm2pl homepage is http://www\&.ntg\&.nl/afm2pl\&.html: \fIhttp://www.ntg.nl/afm2pl.html\fR\&.
-
-.SH AUTHOR
-Siep Kroonenberg <ntg\-afm2pl@ntg\&.nl>.
+.SH "CHANGED IN VERSION 0.7.1"
+.PP
+In order to avoid name conflicts, the \&.enc\- and \&.lig files distributed with afm2pl got
+afm2pl\-
+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\&.
+.SH "URLS"
+.PP
+The afm2pl homepage is
+\fIhttp://www\&.ntg\&.nl/afm2pl\&.html\fR\&.
+.PP
+The paper
+\fIFont installation the shallow way\fR\&[2]
+(EuroTeX 2006 Proceedings, published as
+\fITUGboat\fR\&[3]
+issue 27\&.1) illustrates the use of afm2pl\&.
+.SH "NOTES"
+.IP " 1." 4
+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.
+.IP " 2." 4
+Font installation the shallow way
+.RS 4
+\%http://www.tug.org/TUGboat/Articles/tb27-1/tb86kroonenberg-fonts.pdf
+.RE
+.IP " 3." 4
+TUGboat
+.RS 4
+\%http://www.tug.org/TUGboat/
+.RE
diff --git a/Build/source/texk/afm2pl/afm2pl.c b/Build/source/texk/afm2pl/afm2pl.c
index aeac410f1c6..243a02d1e8a 100644
--- a/Build/source/texk/afm2pl/afm2pl.c
+++ b/Build/source/texk/afm2pl/afm2pl.c
@@ -1,5 +1,5 @@
 /* afm2pl
- * Copyright (C) 2002, 2005 Siep Kroonenberg
+ * Copyright (C) 2002, 2005, 2009 Siep Kroonenberg
  * ntg-afm2pl@ntg.nl
  * based on afm2tfm.
  */
@@ -194,7 +194,7 @@ struct encoding *outencoding = NULL;
 char *ligoption = "1";          /* which extra ligkerns? */
 char *Ligoption = "1";          /* extra ligkern info after letterspacing */
 int based_on;                   /* name output file based on name afm file? */
-
+int no_prefix = 0;              /* don't look for afm2pl- prefixed filenames */
 FILE *infile, *outfile;
 char *afmname, *outname;        /* names of input and output files */
 char *encfilename;              /* encoding file */
@@ -452,10 +452,20 @@ openin(char *fname, kpse_file_format_type format, char *ext)
   char *realfname;
 
 #ifdef KPATHSEA
-  realfname = kpse_find_file (fname, format, false);
+  realfname = NULL;
+  if (!no_prefix && (!strcmp(ext, ".enc") || !strcmp(ext, ".lig"))) {
+    realfname = kpse_find_file (concat("afm2pl-", fname), format, false);
+    if (!realfname) {
+      realfname = concat (concat("afm2pl-", fname), ext);
+      realfname = kpse_find_file (realfname, format, false);
+    }
+  }
   if (!realfname) {
-    realfname = concat (fname, ext);
-    realfname = kpse_find_file (realfname, format, false);
+    realfname = kpse_find_file (fname, format, false);
+    if (!realfname) {
+      realfname = concat (fname, ext);
+      realfname = kpse_find_file (realfname, format, false);
+    }
   }
   if (!realfname)
     FATAL1 ("%s not found", fname);
@@ -1978,11 +1988,11 @@ version(FILE *f)
 #ifdef KPATHSEA
   extern KPSEDLL char *kpathsea_version_string;
 #endif
-  fputs ("afm2pl(k) 0.7.03\n", f);
+  fputs ("afm2pl(k) 0.7.1\n", f);
 #ifdef KPATHSEA
   fprintf (f, "%s\n", kpathsea_version_string);
 #endif
-  fputs ("Copyright (C) 2002, 2005 Siep Kroonenberg.\n\
+  fputs ("Copyright (C) 2002, 2005, 2009 Siep Kroonenberg.\n\
 This program is derived from afm2tfm, (C) 2002 Radical Eye Software.\n\
 There is NO warranty.  You may redistribute this software\n\
 under the terms of the GNU General Public License.\n\
@@ -2204,6 +2214,11 @@ readargs(int argc, char **argv)
       argv += 1;
       argc -= 1;
       break;
+    case 'n':
+      no_prefix = 1;
+      argv += 1;
+      argc -= 1;
+      break;
     case 'V':
       verbose = 1;
       argv += 1;
diff --git a/Build/source/texk/afm2pl/afm2pl.xml b/Build/source/texk/afm2pl/afm2pl.xml
index 7e7717d2135..68648d62c14 100644
--- a/Build/source/texk/afm2pl/afm2pl.xml
+++ b/Build/source/texk/afm2pl/afm2pl.xml
@@ -1,30 +1,12 @@
 <?xml version='1.0' standalone="no"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
   <!ENTITY szlig "&#x00DF;">
 ]>
-<article>
-<articleinfo>
-  <title>afm2pl</title>
-  <author>
-    <firstname>Siep</firstname>
-    <surname>Kroonenberg</surname>
-    <affiliation>
-      <address><email>ntg-afm2pl@ntg.nl</email></address>
-    </affiliation>
-  </author>
-
-  <copyright>
-    <year>2004</year>
-    <holder>Siep Kroonenberg</holder>
-  </copyright>
-</articleinfo>
-
 <refentry>
 <refentryinfo>
   <title>afm2pl</title>
-  <date>February 2004</date>
-  <!--productname Linux /productname-->
+  <date>May 2009</date>
 </refentryinfo>
 
 <refmeta>
@@ -64,6 +46,7 @@
     <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>
@@ -81,17 +64,19 @@
 <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 preserves kerns and ligatures.</para>
+(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 replacement for afm2tfm, on which it
-is based. With afm2tfm, preserving kerns and ligatures is possible
-only in a roundabout way.</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 the recommended encoding
-to be used with afm2pl.  This gives you a good character set with
-all the more important accented characters and many typographic
-symbols available as single characters, without a need for either
-virtual fonts or a separate text companion font.</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
@@ -99,16 +84,16 @@ teTeX. These distributions also contain the encoding file
 texnansi.enc.</para>
 
 <para>The distribution contains uppercased and lowercased versions
-of texnansi, viz. texnanuc.enc and texnanlc.enc, 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).  </para>
+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 successfull but glyphs are missing, and 1 in case of
-error.</para>
+number of missing glyphs if conversion was otherwise successfull but
+glyphs are missing, and 1 in case of error.</para>
 </refsect1>
 
 <refsect1>
@@ -117,11 +102,14 @@ error.</para>
 <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). 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>
+    <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>
 
@@ -137,11 +125,12 @@ error.</para>
   <listitem>
     <para>Widen or narrow characters by
       <replaceable>extend_factor</replaceable>. Default is 1.0
-      (natural width). Not recommended, 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.</para>
+      (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>
 
@@ -150,7 +139,7 @@ error.</para>
   <listitem>
     <para>Oblique (slant) characters by
     <replaceable>slant_factor</replaceable>.
-    Not recommended.</para>
+    Not recommended either.</para>
   </listitem>
 </varlistentry>
 
@@ -276,11 +265,14 @@ error.</para>
   <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.</para>
+    <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>
 
@@ -295,11 +287,21 @@ error.</para>
 </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. This is not particularly
-    logical, but this way the glyph names can be captured even under Windows.
+    glyphs to stderr and their names to stdout.
     </para>
   </listitem>
 </varlistentry>
@@ -324,17 +326,24 @@ error.</para>
 <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, although, in case of a
-geometrically transformed font, it may be better to remove the
-PostScript name for a pdftex mapfile entry.  It is assumed that the
+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. It
-appears that pdftex automatically will consult a mapfile xxx.map for
-a font xxx.</para>
+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">
@@ -347,11 +356,12 @@ and to accept the default behavior.</emphasis></para>
 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 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>
+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>
@@ -411,7 +421,8 @@ 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:</para>
+boundarychar. Below, <literal>space</literal> is the unencoded
+character:</para>
 
 <screen>
 || &lt;&gt; space ;
@@ -457,20 +468,21 @@ 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.  The tfm
-format has room for only about 180x180 ligatures and kerning pairs.
-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
+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
+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>
 
@@ -478,13 +490,42 @@ pairs.</para></listitem> </orderedlist>
 <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.
-The distribution contains an example ucshape.tex on how to use such
-fonts with LaTeX font selection.</para>
+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.</para>
+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>
@@ -512,7 +553,8 @@ that to work.</para>
 
 <refsect1>
 <title>Afm2pl, fontinst and artificial smallcaps</title>
-<para>Afm2pl currently doesn't do virtual fonts. That means that for
+
+<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>
@@ -531,26 +573,26 @@ useable as PostScript names.</para>
 </refsect1>
 
 <refsect1>
-<title>Future plans</title>
-
-<para>I am considering a revision which makes afm2pl a more complete
-replacement for afm2tfm. In that version, afm2pl can optionally
-create a second, virtual font, possibly with a different encoding
-and possibly letterspaced. The current option of non-virtual
-letterspacing via kerns will be dropped. If the encodings differ
-then it is assumed that the virtual font is intended as a small-caps
-version of the main font, and a scaling parameter can be
-specified for non-matching glyphs.</para> </refsect1>
-
-<refsect1>
-<title>Copyright</title>
-<para>The afm2pl distribution is subject to the GNU General Public Licence
-(GPL). Please refer to the file COPYING for details.</para>
+<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://www.ntg.nl/afm2pl.html">http://www.ntg.nl/afm2pl.html</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>
-</article>
-