.TH MKPKFONTDIR 1 "14 August 1995" "TeX Utilities" \" -*- nroff -*-
.SH NAME
mkpkfontdir \- reorganize TeX pk fonts directories
.SH SYNOPSY
.B mkpkfontdir
[
.BI "\-\-version"
]
[
.BI "\-h\fR,\fP \-\-help"
]
[
.BI "\-v\fR,\fP \-\-verbose"
]
[
.BI "\-w\fR,\fP \-\-write-paths"
]
[
.BI "\-n\fR,\fP \-\-noaction"
]
[
.BI "\-m\fR,\fP \-\-mode " modespec
]
[
.B "\-M\fR,\fP \-\-use-modesmf "
[
.I f
]
]
[
.BI "\-T\fR,\fP \-\-use-pktype "
]
[
.BI "\-g\fR,\fP \-\-guess-mode"
]
[
.BI "\-f\fR,\fP \-\-fontdir " fontdir
]
[
.BI "\-d\fR,\fP \-\-destdir " destdir
]
[
.BI "\-o\fR,\fP \-\-overwrite"
]
[
.BI "\-l\fR,\fP \-\-link"
|
.BI "\-s\fR,\fP \-\-symbolic-link"
]
[
.BI "\-t\fR,\fP \-\-tds-names"
]
[
.BI "\-L\fR,\fP \-\-long-names"
]
[
.BI "\-p\fR,\fP \-\-prune " n
|
.BI "\-P\fR,\fP \-r\fR,\fP \-\-restrict " n
]
.IR "directory-or-pkfile " ".\|.\|."
.SH DESCRIPTION
.BR mkpkfontdir
rearranges TeX pk font files in directories, making them conform to a
particular structure, such as the TeX Directory Structure (TDS) and
variants of it. It can 
also make links to an existing directory structure that respect
another kind of structure (this may be useful for example to optimize
the search time of fonts that are located in a standard TDS on a
readonly media, by making a pool of links to the files, the pool being
the first directory searched by the programs needing the fonts).
.PP
.BR mkpkfontdir
associates a
.I "font path"
to each font on the system, by looking where its tfm file is
located. For instance, with the TDS, the metrics file for the American
Mathematical Society (AMS) Euler font eurm10 is located in
texmf/fonts/tfm/ams/euler/eurm10.tfm, which yields a font path of
ams/euler.
.PP
Once a given font's font path is known,
.BR texfondir
uses it to relocate its pk files in a destination directory.
The relocated files have a path that is the concatenation of the
path for pk files in the destination directory, the mode corresponding
to the font file, the (maybe modified)
font path and the name of the pk file (henceforth
.IR "pk name" ")."
This name is a combination of
the font name and its resolution: on a Unix system, for example, the
pk name of the eur10 font at 300 dpi is eur10.300pk; in a TDS hierarchy,
however, it is dpi300/eur10.pk because names are limited to 8
characters plus a 3 characters extension.
.PP
.BR mkpkfontdir
uses
kpsewhich(1)
to locate tfm files, or a
find(1)
under the
.I fontdir
directory if the former is not available on your
system. Once the file has been located, it assumes that the font path
starts after a component of the file path named
@@LOC_TFMDIRBASE@@. (If
kpswewhich(1)
is not available on your system,
.B mkpkfontdir
assumes that your tfm files are located in a @@LOC_TFMDIR@@
directory under the
.I fontdir
directory; this is to accelerate the
search.)

On this system,
.BR mkpkfontdir
has been configured to know that pk files are located
in a @@LOC_PKDIR@@ directory under the fonts directory (this is
actually the TDS hierarchy). This means that indvidual pk files will
be moved to
.IR destdir "/@@LOC_PKDIR@@."
unless their tfm file have not been found, in which case they will go
to
.IR "/@@LOC_UNKNOWNDIR@@.:
.PP
The mode of a font file is determined with the following rules: first,
get the user-supplied mode if there is one; if there isn't,
try to get the mode from the font file itself, with
pktype(1)
(if the
.B \-\-use-pktype
option has been used); if this still does not yields a mode, look the
file full path and try to guess it (by default or if the
.B \-\-guess-mode
option has been used together with the
.B \-\-use-pktype
one). Once we have found a mode, and if the
.B \-\-use-modesmf
option has been given, this
mode is validated by looking into the modes.mf modes file. If the mode
is there, keep it, otherwise try to guess the mode by looking at
the file path (this is not done by default if pktype was called).
If we finally do not have a mode, use @@LOC_UNKNOWNMODE@@.
Note that the mode is only validated once, not each
time one is found, i.e. if you specify an invalid mode on the
command-line all files will effectively get @@LOC_UNKNOWNMODE@@ as mode.
.PP
Because
.BR mkpkfontdir
sort of mirror the hierarchy of the tfm files, it is a convenient
tool for installing fonts: once the tfm files are correctly installed,
the pk files can be installed as a pool first, and then be moved
automatically by
.B mkpkfontdir
in order to use the fonts directory structure in force at the
site.
.PP
.BR mkpkfontdir
creates directories as needed, and does also remove them: after a file
has been moved, it recursively destroys empties directories on the
original path (which means that if you transform your pool structure
in a TDS and then transform it back into a pool, you will not have
unwanted empty directories; it also means that if you do not want some
directories to be destroyed, you can put a dummy file whose name does not
end in pk in them).
.SH OPTIONS
Unless told otherwise below, non-boolean
options may be abbreviated to their first letter.
In addition, if the POSIXLY_CORRECT environment variable is not set, they may
be abbreviated to uniqueness.
.TP
.BI "\-\-version"
Print the version of
.BR mkpkfontdir
on standard output and exit.
.TP
.BI "\-h\fR,\fP \-\-help"
Print usage and a short explanantion of the different options on
standard output and exit.
.TP
.BI "\-v\fR,\fP \-\-verbose"
Print informations about what is done on standard output. For each
font file, a line is printed indicating its path, then another line
indicating its new path. The first characters of this second line
indicate what is done: `=>' means that the file is moved, `->' means
that a symbolic link is make and `+>' means that a hard link is made
(when doing links,
.BR mkpkfontdir
does not remove the original file).
.TP
.BI "\-w\fR,\fP \-\-write-paths"
Print the path of each font file to standard output. The path is written
even if an error occurs (e.g. if the file cannot be moved, its old location
will be printed). If the
.B \-\-noaction
option is used, of course, the path may be wrong because files are not
effectively moved or linked, hence errors doing these actions cannot be
discovered.
.TP
.BI "\-n\fR,\fP \-\-noaction"
Do not do anything, really. But continue to fo verbose output if
asked, and still issue warnings on standard error. Can be used to
check for the correctness of the actions before doing them really.
.TP
.BI "\-m\fR,\fP \-\-mode " modespec
Use the
.I modespec
string as modes definitions. This string is made of comma-separated
modes definitions of the form
.I alias\fR=[\fPmode\fR]\fP
meaning that if a font has mode
.I alias
it will be moved under mode
.I mode
(which is useful if you always use mode cx, for example, and have fonts with
CanonCX modes in them but want them to be under the cx hierarchy
because the modes are identical). If
.I mode
is not supplied, then
.I alias
will be the default mode.
Note that
.I mode
(or
.I alias
if
.I mode
was not supplied) must be present in the modes.mf modes file if the
.B \-\-use-modesmf
option has been given, or the
directive will be ignored.
.TP
.BI "\-M\fR,\fP \-\-use-modesmf " f
Use a modes.mf file; eventually specifiy that
.I f
is the modes.mf modes file to be used.
.TP
.BI "\-T\fR,\fP \-\-use-pktype"
Use
pktype(1)
to determine the mode of a font file. This implies that the mode will
not be guessed by looking at the font file full path.
.TP
.BI "\-g\fR,\fP \-\-guess-mode"
Force guessing of the mode by looking at the font file full path.
.TP
.BI "\-f\fR,\fP \-\-fontdir " fontdir
Specify the font directory under which the tfm files will be found.
.TP
.BI "\-d\fR,\fP \-\-destdir " destdir
Specify the font directory under which the files will be moved (or
where links will be created).
.TP
.BI "\-o\fR,\fP \-\-overwrite"
Overwrite existing files. Default is to issue a warning and to go on
to the next file.
.TP
.BI "\-l\fR,\fP \-\-link"
Instead of moving files, create a link.
.TP
.BI "\-s\fR,\fP \-\-symbolic-link"
Instead of moving files, create a symbolic link. (On systems that do
not support symbolic links, a hard link will be created instead.)
.TP
.BI "\-t\fR,\fP \-\-tds-names"
Use TDS names (e.g. dpi300/cmr10.pk) for pk files.
.TP
.BI "\-L\fR,\fP \-\-long-names"
Use long names (e.g. cmr10.300pk) for pk files.
.TP
.BI "\-p\fR,\fP \-\-prune " n
Removes
.I n
levels of subdirectories from the font path, starting from the
end. (For example, removing one level of subdirectories from public/cm
yields public).
.TP
.BI "\-P\fR,\fP \-R\fR,\fP \-\-restrict " n
Restrict the depth of the font path to
.I n
- 1. (For example, if the argument is 2, public/cm yields public.) To
remember this silly thing, you can think of the length of the font path
plus the pk file name (and remember that still with an argument of 2,
public/cm/dpi300/cmr10.pk will yield
public/dpi300/cmr10.pk because dpi300/cmr10pk is the pk file name).
.SH EXAMPLES
To rearrange all your fonts in a TDS structure, simply say
.PP
.RS
.BR mkpkfontdir
\-t /path/to/pkfiles
.RE
.PP
To get them classified only by supplier and typeface, say
.PP
.RS
.BR mkpkfontdir
/path/to/pkfiles
.RE
.PP
To make a pool of all the pk files, say
.PP
.RS
.BR mkpkfontdir
-r 0 /path/to/pkfiles
.RE
.PP
which suppresses all subdirectories.
.PP
To make pools of the pk files organized by suppliers, say
.PP
.RS
.BR mkpkfontdir
\-r 2 /path/to/pkfiles
.RE
.PP
which suppresses all subdirectories but the supplier one (the 2 is
here because we have the font path and the pk file name, and even if
it is made of a directory and a file name in the TDS case, it is
counted as just one level; this is good because it means that one
cannot mistakenly move all font.pk files of different resolutions in a
single directory, thus losing all resolutions but one for each pk
file).
.PP
To move all fonts with mode CanonCX or unknown under the cx
directories, say
.PP
.RS
.BR mkpkfontdir
-T -m CanonCX=cx,cx /path/to/pkfiles
.RE
.PP
To make a pool of (symbolic) links optimizing recursive subdirectory
search by offering at most one level of search (on a system limited to
TDS names), say
.PP
.RS
.BR mkpkfontdir
-s -d /path/to/pool /path/to/pkfiles
.RE
.SH RESTRICTIONS
Some systems do not support long file names ;-) This is why
.B mkpkfontdir
may have been configured to either refuse long names or guess if it is
possible to create them. If long names are not available or not
supported, the use of long names option will cause an error. On a
correctly configured installation,
.B mkpkfontdir
should create by default files whose names respect the local naming
conventions, and let anyone create files with TDS names.
.SH CAVEATS AND BUGS
Using a real TDS tree is somewhat penalizing: on the author's system,
with only the TeX, LaTeX and AMS fonts installed, starting
xdvi(1)
(using kpathsea 2.6) takes
approximatively 15 seconds, while when the files are organized in a
pool (eventually of links) with only one level of subdirectories (the
suppliers), it starts in 2 seconds.
.PP
The program asusmes that pk files have names ending in
.IR pk "."
Unless your installation has suffered from tortuous changes, this will
never be a problem.
.PP
The argument to the
.B \-\-restrict
option is unnatural, it should be the number of directories levels we
want, not this number plus one.
.PP
The
.I directory
argument can be a file. This is actually a feature (I just removed the
test for a directory), that may be used for moving a single file.
.SH AUTHOR
Yves Arrouye <Yves.Arrouye@imag.fr>.
.SH VERSION
The
.B mkpkfontdir
utility described in this manual page has version 1.1 (August 1995).
.SH ENVIRONMENT
.TP 20
$TEXMF
Top directory of the main TDS-like hierarchy (defaults to @@TEXMF@@).
.TP 20
$VARTEXMF
Top directory of a writable TDS-like hierarchy (defaults to $TEXMF).
.SH FILES
.TP 20
@@LOC_MODESMF@@
MetaFont modes descriptions.
.SH SEE ALSO
.TP 20
TWG-TDS
A Directory Structure for TeX files
.TP 20
MakeTeXPK(1)
A tool for generated TeX pk files as needed
.TP 20
kpsewhich(1)
A tool to locate files using kpathsea
.TP 20
pktype(1)
A tool disassembling the contents of a .pk file
.TP 20
modes.mf(5)
The database of MetaFont modes descriptions.