summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/fontinst/base/fimapgen.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/fontinst/base/fimapgen.dtx')
-rw-r--r--Master/texmf-dist/source/fontinst/base/fimapgen.dtx1533
1 files changed, 1533 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/fontinst/base/fimapgen.dtx b/Master/texmf-dist/source/fontinst/base/fimapgen.dtx
new file mode 100644
index 00000000000..bce3a5a99fd
--- /dev/null
+++ b/Master/texmf-dist/source/fontinst/base/fimapgen.dtx
@@ -0,0 +1,1533 @@
+% \CheckSum{873}
+% \iffalse meta-comment
+%
+% Copyright 1999 the fontinst maintenance team and any individual
+% authors listed elsewhere in this file. All rights reserved.
+%
+% This file is part of the fontinst system version 1.9.
+% -----------------------------------------------------
+%
+% It may be distributed under the terms of the LaTeX Project Public
+% License, as described in lppl.txt in the base LaTeX distribution.
+% Either version 1.0 or, at your option, any later version.
+%
+%%% From file: fimapgen.dtx
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{fisource}
+
+\title{\texttt{fimapgen.dtx}}
+\author{Lars Hellstr\"om}
+\begin{document}
+\maketitle
+
+\DocInput{fimapgen.dtx}
+
+\end{document}
+%</driver>
+% \fi
+%
+%
+% \section{Generating map file fragments}
+% \label{Sec:Mapfiles}
+% \changes{1.904}{1999/06/15}{Completed rudimentary map file fragment
+% generator, made it part of \texttt{finstmsc.sty}. (LH)}
+% \newcommand\OzTeX{O\kern-.03em z\kern-.15em\TeX}
+%
+% A \emph{map file} is a file which is used by some DVI driver to link
+% various kinds of font information to each other, as is needed for the
+% driver's operation. Examples of such files are the file
+% \texttt{psfonts.map} used by \texttt{dvips} and the config files of
+% \OzTeX. There are however many other such files around in the \TeX\
+% world.
+%
+% Not all of a map file need to be related to linking specific kinds of
+% font information to each other. \OzTeX\ config files can for example
+% be used to set the values of \TeX\ implementation parameters\footnote
+% {The kind of things that were Pascal constants in the original \Web\
+% sources for \TeX.} and there need not be any font-related information
+% at all in them. The important thing is however that there can be map
+% information in them---that information could be automatically written
+% by the routines described here.
+%
+% Since there may be other kinds of information in these files (and often
+% enough need to be for everthing to work right), the routines described
+% here will only generate map file \emph{fragments}. These fragments
+% will then have to be inserted in the final map files somehow, usually
+% through manual editing. The purpose of the routines described here is
+% only to save the user a good deal of (often quite boring) typing, not
+% to actually install everything where it needs to be.
+%
+% \StopEventually{}
+%
+% \begin{macro}{\mapfrags_subsystem}
+% This macro holds the name of the automatic map file fragments
+% writer subsystem of \package{fontinst}, as it appears in error
+% messages.
+% \begin{macrocode}
+\def\mapfrags_subsystem{Map~fragments~writer}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Interface to main \package{fontinst}}
+% \label{Ssec:interface}
+%
+% The automatic generation of map file fragments is based on the two
+% commands |\storemapdata| and |\makemapentry|. Their respective
+% syntaxes are
+% \begin{quote}
+% |\storemapdata|\marg{\TeX\ font name}\marg{source}^^A
+% \marg{transforms}\\
+% |\makemapentry|\marg{\TeX\ font name}
+% \end{quote}
+%
+% \DescribeMacro{\storemapdata}|\storemapdata| commands are written when
+% a metric file \meta{\TeX\ font name}|.mtx| is generated. The purpose
+% of these commands is to record where the data for that file came from,
+% and what was done to these data. The source of the data is specified
+% in the \meta{source} argument, which can contain one of
+% \begin{quote}
+% |\fromafm|\marg{AFM name}\marg{PS name}\\
+% |\frompl|\marg{PL name}\\
+% |\frommtx|\marg{MTX name}\\
+% |\fromvpl|
+% \end{quote}
+% The only real difference between |\fromafm| and |\frompl| at this
+% stage is that the former specifies the PS name of the font, but the
+% latter do not. If you write a |\store|\-|map|\-|data| command yourself
+% and want to supply the PS name then you should use |\fromafm| even if
+% you took the font metrics from a PL.
+% There is a important difference between |\fromvpl| and the first three
+% in that virtual fonts need no map file entry (and hence there should
+% not be any either). Besides some error checking, |\fromvpl| causes a
+% |\makemapentry| to do essentially nothing.
+%
+% What was done to the data is specified by the \meta{transforms}
+% argument, which is a possibly empty sequence of commands, in which
+% each item is one of
+% \begin{isyntax}
+% |\transformfont|\marg{x-scale}\marg{slant-scale}\\
+% |\reencodefont|\marg{etx}\\
+% |\reglyphfont|
+% \end{isyntax}
+% The order is interpreted so that the thing done first appear first in
+% the sequence. In normal cases there is at most one of each, and then
+% the order is not important. \meta{x-scale}, \meta{slant-scale}, and
+% \meta{y-scale} are the values of these variables used for the
+% transformation, as \TeX\ numbers. \meta{etx} is the name of the ETX
+% file used for the font reencoding.
+% |\reglyphfont| is an error marker. It will not be encountered (but
+% it may well get stored in some table) unless a metric font transform
+% is applied to a font that has been reglyphed, which is illegal.
+%
+% \changes{1.911}{1999/11/17}{\cs{storemapdata} commands are also
+% written to metric files when they are generated. (LH)}
+% In addition to being written to a transforms record file (if one is
+% open), |\storemapdata| commands are also written to the actual metric
+% file. This makes it possible to find out where the data for a file
+% comes from even if the file was made on a previous \package{fontinst}
+% run, but since it requires reading an additional file just to find one
+% command, it will be slower than if the |\storemapdata| appeared in a
+% transforms records file.
+%
+% \DescribeMacro{\makemapentry}|\makemapentry| commands are written when
+% a VPL that uses or a ligfull PL for a font is generated. These
+% commands are the ones which actually cause the map file fragment
+% generator to write an entry, but entries are only written if they
+% haven't been written before. |\makemapentry| uses information that
+% was stored by a previous call to |\storemapdata|.
+%
+% |\storemapdata| stores its arguments in one of the control sequences
+% \describecsfamily{Tf-\meta{font}}|\Tf-|\meta{font}, where \meta{font}
+% is the same thing as \meta{\TeX\ font name} above. |Tf| stands for
+% ``\TeX\ font''. The control sequences in this family are paramterless
+% macros whose replacement texts have the following form:
+% \changes{1.914}{2000/05/30}{Contents of \cs{Tf-\meta{font}} control
+% sequences changed to allow processing the same file of recorded
+% transformations several times on the same run. (LH)}
+% \begin{quote}
+% \marg{made}\marg{source}\marg{transforms}
+% \end{quote}
+% Here \meta{source} and \meta{transforms} are exactly as above.
+% \meta{made} is a number which describes the current status of this font.
+% If \meta{made} is even then the font has been defined but no entry for
+% it has subsequently been written to the map file, whereas if it is odd
+% then an entry for it has been written to the map file. If the value of
+% \meta{made} is less than |\process_generation| then the data in the
+% other two arguments is from a previous run and should be ignored.
+% The |\Tf-|\meta{font} control sequences should always be set globally.
+%
+% \begin{macro}{\process_generation}
+% \begin{macro}{\process_generation_succ}
+% |\process_generation| is a counter which stores the number of the
+% current ``entry generation''. It starts at 0 and is increased by
+% two at each |\donedrivers|. |\process_generation_succ| is a macro
+% which expands to a number one larger than that in |\process_generation|.
+% \multchanges{\cs{process_generation}\cs{process_generation_succ}}
+% {1.914}{2000/05/30}{Control sequences added. (LH)}
+% \begin{macrocode}
+%<*map>
+\newcount\process_generation
+\process_generation=0
+\def\process_generation_succ{1}
+%</map>
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+% \begin{macro}{\recordtransforms}
+% \begin{macro}{\endrecordtransforms}
+% \begin{macro}{\transform_record_file}
+% In main \package{fontinst}, the command
+% \begin{quote}
+% |\recordtransforms|\marg{filename}
+% \end{quote}
+% starts a block of code within which font transforms will be recorded
+% in the file \meta{filename}. |\endrecordtransforms| ends such a block.
+% \begin{macrocode}
+%<*pkg>
+\def\recordtransforms#1{\open_pout\transform_record_file{#1}}
+\def\endrecordtransforms{
+ \close_pout\transform_record_file{Font~transformation~records}
+}
+\chardef\transform_record_file=\closed_stream
+%</pkg>
+% \end{macrocode}
+% \end{macro} \end{macro} \end{macro}
+%
+%
+% \begin{macro}{\extract_font_generation}
+% The |\extract_font_generation| macro takes the name of a font and
+% returns the \meta{made} component from the |\Tf-|\meta{font} macro
+% for that font, or minus one if that macro hasn't been defined.
+% \changes{1.914}{2000/05/30}{Macro added. (LH)}
+% \begin{macrocode}
+%<*map>
+\def\extract_font_generation#1{
+ \if_defined{Tf-#1}\then
+ \expandafter\expandafter \expandafter\first_of_three
+ \csname Tf-#1\endcsname
+ \else
+ \m@ne
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\storemapdata}
+% There should not be two |\storemapdata| for the same font, hence
+% the check below. (Note that a `font' in this case is an MTX file.
+% It is quite possible (and legal) to generate the PL file for that
+% MTX file more than once.)
+% \changes{1.927}{2004/07/12}{Improved wording of warning message
+% and downgraded it to an info in the case when the two
+% definitions are the same. (LH)}
+% \begin{macrocode}
+\def\storemapdata#1#2#3{
+ \expandafter\def \expandafter\a_macro
+ \expandafter{ \expandafter{ \the\process_generation}{#2}{#3}}
+ \ifnum \extract_font_generation{#1}<\process_generation \else
+ \x_cs\ifx{Tf-#1}\a_macro
+ \fontinstinfo\mapfrags_subsystem
+ {Repeated~definition~of~font~#1}
+ \else
+ \fontinstwarning\mapfrags_subsystem
+ {Inconsistent~redefinition~of~font~#1}
+ \fi
+ \fi
+ \x_cs\let{Tf-#1}=\a_macro
+}
+%</map>
+% \end{macrocode}
+% In main \package{fontinst}, |\storemapdata| should be a noop so
+% that it can appear in metric files.
+% \begin{macrocode}
+%<pkg>\let\storemapdata=\gobble_three
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\record_transform}
+% \changes{1.911}{1999/11/18}{\cs{storemapdata} lines are optionally
+% written to the main output file as well. (LH)}
+% In main \package{fontinst}, the call
+% \begin{quote}
+% |\record_transform|\marg{TFM name}\marg{source}^^A
+% \marg{transforms}\marg{if}
+% \end{quote}
+% writes
+% \begin{quote}
+% |\storemapdata|\marg{TFM name}\marg{source}\marg{transforms}
+% \end{quote}
+% to the transformation recordings file (if font transforms are being
+% recorded) and to the main output file (if the \meta{if} evaluates
+% to true). Note that the caller of |\record_transform| must see to
+% that macros in \meta{source} and \meta{transforms} are written
+% correctly to the file (this is usually accomplished by adding
+% |\string| in suitable places of these arguments during their
+% construction).
+%
+% \begin{macrocode}
+%<*pkg>
+\def\record_transform#1#2#3#4{
+ \ifnum \transform_record_file=\closed_stream \else
+ \pout_line\transform_record_file{\string\storemapdata{#1}{#2}{#3}}
+ \fi
+ #4 \out_line{\string\storemapdata{#1}{#2}{#3}} \fi
+}
+%</pkg>
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\transformfont}
+% \changes{1.913}{2000/03/11}{Third argument removed, since it isn't
+% used anymore. This change is harmless, since the worst thing
+% that can happen to this argument is that it is typeset. (LH)}
+% \begin{macro}{\reencodefont}
+% \begin{macro}{\reglyphfont}
+% These are initially |\relax|, so they can be |\edef|ed with safely.
+% \begin{macrocode}
+%<*map>
+\let\transformfont\x_relax
+\let\reencodefont\x_relax
+\let\reglyphfont\x_relax
+% \end{macrocode}
+% \end{macro}\end{macro}\end{macro}
+%
+%
+% \changes{1.914}{2000/05/30}{The total transform applied for a font is
+% determined before the entry makers are called. (LH)}
+% \begin{macro}{\makemapentry}
+% |\makemapentry| sets |\TeX_font_name|, checks if any map data have
+% been stored for the font in question, and passes them on to
+% |\make_map_entry| if they have; otherwise it raises an error. There
+% is also a group which is begun and ended by |\makemapentry|, to stop
+% values deduced for one entry to interfere with the deduction of values
+% in the following.
+% \changes{1.911}{1999/11/20}{When map data are not known, try to
+% get them from the MTX file before declaring the source unknown.
+% (LH)}
+% \begin{macrocode}
+\def\makemapentry#1{\begingroup
+ \def\TeX_font_name{#1}
+ \ifnum \extract_font_generation{#1}<\process_generation
+ \if_file_exists{#1.mtx}\then
+ \inputmtx{#1}
+ \fi\fi
+ \ifnum \extract_font_generation{#1}<\process_generation
+ \from_unknown{#1}
+ \x_cs\xdef{Tf-#1}{
+ {\process_generation_succ}{\noexpand\from_unknown{#1}}{}
+ }
+ \else
+ \expandafter\expandafter \expandafter\make_map_entry
+ \csname Tf-#1\endcsname
+ \fi
+ \endgroup
+}
+% \end{macrocode}
+%
+% \begin{macro}{\make_map_entry}
+% |\make_map_entry| oversees the interpretation of the
+% \meta{source} part of the map data, something which sets
+% |\source_font_TeX_name| and possibly |\PS_font_name|. It also
+% collects the transforms applied in |\font_transforms|,
+% concatenates them, and calls a list macro |\entry_makers_list| which
+% causes the actual entries to be written, and records in
+% |\Tf-|\meta{\TeX\ font name} that the entries have been written.
+% \begin{macrocode}
+\def\make_map_entry#1#2#3{
+ \ifnum #1=\process_generation
+ \def\font_transforms{#3}
+ #2
+ \_a_false
+ \let\transformfont\concat_transformfont
+ \let\reencodefont\concat_reencodefont
+ \let\reglyphfont\_a_true
+ \font_transforms
+ \if_a_
+ \fontinsterror\mapfrags_subsystem{
+ \string\makemapentry\space for~reglyphed~font
+ }{ No~entry~for~font~\TeX_font_name\space
+ can~be~written,\messagebreak
+ since~it~had~been~reglyphed!~\error_help_a
+ }
+ \else
+ \entry_makers_list
+ \fi
+ \expandafter\gdef \csname Tf-\TeX_font_name \expandafter\endcsname
+ \expandafter{\expandafter{\process_generation_succ}{#2}{#3}}
+ \fi
+}
+%</map>
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+%
+% \begin{macro}{\record_usage}
+% In main \package{fontinst}, the call
+% \begin{quote}
+% |\record_usage|\marg{TFM name}
+% \end{quote}
+% writes
+% \begin{quote}
+% |\makemapentry|\marg{TFM name}
+% \end{quote}
+% to the transformation recordings file, if font transforms are being
+% recorded. The |\record_usage| command is, roughly speaking, only used
+% by |\installfont| and |\installrawfont|.
+% \begin{macrocode}
+%<*pkg>
+\def\record_usage#1{
+ \ifnum \transform_record_file=\closed_stream \else
+ \pout_line\transform_record_file{\string\makemapentry{#1}}
+ \fi
+}
+%</pkg>
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\fromafm}
+% |\fromafm| saves its two arguments in the suitable string macros.
+% \begin{macrocode}
+%<*map>
+\def\fromafm#1#2{
+ \def\source_font_TeX_name{#1}
+ \def\PS_font_name{#2}
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\frompl}
+% |\frompl| saves its argument in the suitable string macro.
+% \begin{macrocode}
+\def\frompl#1{
+ \def\source_font_TeX_name{#1}
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\frommtx}
+% This one is tricky, since it will have to work recursively,
+% fetching data that were stored for some other font. If it cannot
+% find those data in memory, then it tries to get them from the
+% metric file itself.
+% \changes{1.911}{1999/11/17}{When map data are not known, try to
+% get them from the MTX file before declaring the source unknown.
+% (LH)}
+% \begin{macrocode}
+\def\frommtx#1{%
+ \ifnum \extract_font_generation{#1}<\process_generation
+ \if_file_exists{#1.mtx}\then
+ \inputmtx{#1}
+ \fi\fi
+ \ifnum \extract_font_generation{#1}<\process_generation
+ \from_unknown{#1}
+ \x_cs\xdef{Tf-#1}{
+ {\the\process_generation}{\noexpand\from_unknown{#1}}{}
+ }
+ \else
+ \expandafter\expandafter \expandafter\from_mtx
+ \csname Tf-#1\endcsname
+ \fi
+}
+% \end{macrocode}
+% \begin{macro}{\from_mtx}
+% \begin{macrocode}
+\def\from_mtx#1#2#3{
+ \edef\font_transforms{#3\font_transforms}
+ #2
+}
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+% \begin{macro}{\fromvpl}
+% The |\fromvpl| command checks if |\font_transforms| is empty. If it
+% is then everything is fine, but no entry should be written for this
+% font. If it isn't then someone has tried to make a transformation of
+% a virtual font, which doesn't work.
+% \begin{macrocode}
+\def\fromvpl{
+ \ifx \empty_command\font_transforms \else
+ \fontinsterror\mapfrags_subsystem{
+ Font~is~virtual,~it~cannot~be~transformed}{
+ No~entry~for~font~\TeX_font_name\space can~be~written.
+ \messagebreak\error_help_a
+ }
+ \fi
+ \let\maker_do\gobble_one
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\AssumeMetafont}
+% The |\AssumeMetafont| general settings command makes |\frompl|
+% behave like |\fromvpl|.
+% \begin{macrocode}
+\def\AssumeMetafont{
+ \def\frompl{
+ \ifx \empty_command\font_transforms \else
+ \fontinsterror\mapfrags_subsystem{
+ A~Metafont~cannot~be~transformed}{
+ No~entry~for~font~\TeX_font_name\space can~be~written.
+ \messagebreak\error_help_a
+ }
+ \fi
+ \let\maker_do\gobble_one
+ }
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\from_unknown}
+% This special value for \meta{source} is used for fonts that are
+% referenced by some |\frommtx| but which have no |\storemapdata|
+% themselves.
+% \begin{macrocode}
+\def\from_unknown#1{
+ \fontinstwarningnoline\mapfrags_subsystem{
+ No~map~data~stored~for~font~#1.\messagebreak
+ No~entry~for~\TeX_font_name\space will~be~written,\messagebreak
+ due~to~insufficient~information}
+ \includewarning\warn_unknown_source
+ \let\maker_do\gobble_one
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\font_transforms}
+% This macro is used to collect all transformations that have been
+% applied to a font in, before they are concatenated.
+% \begin{macrocode}
+\let\font_transforms\empty_command
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\xscale_factor}
+% \begin{macro}{\slant_factor}
+% \begin{macro}{\reencode_etx}
+% |\xscale_factor| and |\slant_factor| are dimens which the entry
+% makers can inspect to check the amount of horizontal scaling and
+% slanting should be applied to the current font. 1\,pt equals the
+% factor~1.
+% \begin{quote}
+% |\expandafter\lose_measure\the\xscale_factor|
+% \end{quote}
+% will produce the corresponding factor.
+%
+% |\reencode_etx| is a macro which contains the name of the (last)
+% ETX file used to reencode the font; it is empty if the font hasn't
+% been reencoded.
+% \multchanges{\cs{xscale_factor}\cs{slant_factor}\cs{reencode_etx}}
+% {1.914}{2000/05/30}{Control sequences added. (LH)}
+% \begin{macrocode}
+\newdimen\xscale_factor \newdimen\slant_factor
+\xscale_factor=\p@ \slant_factor=\z@
+\let\reencode_etx\empty_command
+% \end{macrocode}
+% \end{macro}\end{macro}\end{macro}
+%
+% \multchanges{\cs{concat_transformfont}\cs{concat_reencodefont}}
+% {1.914}{2000/05/30}{Macros added. (LH)}
+% \begin{macro}{\concat_transformfont}
+% The |\concat_transformfont| macro is a definition of |\transformfont|
+% which concatenates the transformation expressed by the arguments
+% with the one in |\xscale_factor| and |\slant_factor|.
+% Mathematically, it performs the multiplication
+% $$
+% \left( \begin{array}{cc} f(\#1)& f(\#2)\\ 0& 1 \end{array} \right)
+% \left( \begin{array}{cc}
+% \mbox{\cs{xscale_factor}}& \mbox{\cs{slant_factor}} \\
+% 0& 1
+% \end{array} \right)
+% $$
+% where $f$ stands for |\make_factor|.
+% \begin{macrocode}
+\def\concat_transformfont#1#2{
+ \edef\a_macro{\make_factor{#1}}
+ \xscale_factor=\a_macro\xscale_factor
+ \slant_factor=\a_macro\slant_factor
+ \advance \slant_factor \make_factor{#2}\p@
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\concat_reencodefont}
+% The |\concat_reencodefont| macro is a definition of |\reencodefont|
+% which concatenates the reencoding expressed by the argument with
+% the one in |\reencode_etx|. Since reencoding ignores the previous
+% encoding, concatenating is the same thing as remembering the last
+% reencoding.
+% \begin{macrocode}
+\def\concat_reencodefont#1{\def\reencode_etx{#1}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{User interface}
+%
+% The basic usage of the automatic map file fragment generator consists
+% of specifying for which driver(s) entries should be generated,
+% |\input|ing a file of recorded transformations generated by main
+% \package{fontinst}, and signaling that there isn't anything more to
+% write. This can be done with the commands
+% \begin{quote}
+% |\adddriver|\marg{driver name}\marg{fragment file name}\\
+% \meta{possible additional \cs{adddriver} commands}\\
+% |\input |\meta{recorded transforms file}\\
+% |\donedrivers|\\
+% |\bye|
+% \end{quote}
+% It should however be noted that this is the \emph{basic} usage. The
+% map fragments that work for one \TeX\ system need not work for
+% another (even if the driver is the same), and therefore it is
+% necessary to make the whole process of writing map file fragments
+% configurable. A few examples of things you may have to inform the map
+% fragment writer about are (and these are for \package{dvips} alone;
+% that's the driver I know best):
+% \begin{itemize}
+% \item
+% Is the font resident on the printer or must it be downloaded?
+% \item
+% If the font must be downloaded, what is the name of the file it
+% is in? Here one must take into account not only the possibility
+% that the font file might have to be shared with some other
+% software (such as a GUI) and thus cannot be named according to
+% the Berry scheme---even if it is named according to the Berry
+% scheme one still has the question of its extension: \texttt{.pfa},
+% \texttt{.pfb}, or something else? For instances of Multiple Master
+% fonts, you (at least sometimes) have to download more than one file.
+% \item
+% Again if the font must be downloaded, can/should it be partially
+% downloaded?
+% \item
+% In case the font has been reencoded, what is the name of the file
+% which defines this encoding, and by what name does that file make
+% the encoding known to the postscript interpreter?
+% \end{itemize}
+% The mechanisms available for such configuration are described in
+% Subsection~\ref{Sssec:Config-interface}.
+% Note that map files for DVI viewers are on average more likely to need
+% various platform-specific information about the fonts than map files
+% for DVI printer drivers are, and hence once can expect that
+% generation of these will need more extensive configuration than that
+% for the printer drivers.
+%
+%
+% \subsubsection{Interface for basic usage}
+%
+% An \emph{entry maker} is a group of macros which write the entry for
+% the font currently under consideration to a map fragments file each
+% time they are called. The macro to call must have a name of the form
+% \describecsfamily{make_\meta{driver}}|\make_|\meta{driver} for
+% |\adddriver| to recognise it. Each entry maker has a separate output
+% file (opened using |\open_pout|) and the identifier connected to that
+% file is called \describecsfamily{output_\meta{driver}}\relax
+% |\output_|\meta{driver}.
+%
+% A list of all entry makers currently active is maintined in the macro
+% |\entry_makers_list|. Each item in this list has the form
+% \begin{quote}
+% |\maker_do|\,|\make_|\meta{driver}
+% \end{quote}
+% |\maker_do| is usually |\relax|, but it does occationally get set to
+% other values.
+% \par\bigskip
+%
+%
+% \begin{macro}{\adddriver}
+% The |\adddriver| command adds the named driver to the list of
+% drivers to write entries for and opens an output file where the
+% entries for that particular driver will go. Repeated calls to
+% |\adddriver| for the same driver have no effect.
+% \begin{macrocode}
+\def\adddriver#1#2{
+ \x_cs\ifx{make_#1}\x_relax
+ \fontinsterror\mapfrags_subsystem
+ {There~is~no~entry~maker~for~#1}\error_help_a
+ \else
+ \x_cs\ifx{output_#1}\x_relax \_a_true \else
+ \x_cs\ifx{output_#1}\closed_stream \_a_true \else
+ \_a_false
+ \fi\fi
+ \if_a_
+ \x_cs\open_pout{output_#1}{#2}
+ \expandafter\add_to \expandafter\entry_makers_list
+ \expandafter{ \expandafter\maker_do
+ \csname make_#1\endcsname}
+ \fi
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\entry_makers_list}
+% \begin{macro}{\maker_do}
+% \begin{macrocode}
+\let\entry_makers_list\empty_command
+\let\maker_do\x_relax
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+% \begin{macro}{\donedrivers}
+% The main function performed by the |\donedrivers| command is to
+% close all the open output files. It might also print some warning
+% messages.
+% \begin{macrocode}
+\def\donedrivers{
+ \def\maker_do##1{
+ \x_cs\close_pout{output\expandafter\gobble_five\string##1}
+ {Map~file~fragments}
+ }
+ \entry_makers_list
+ \let\maker_do\x_relax
+ \let\entry_makers_list\empty_command
+ \errorstopmode
+ \reportwarnings
+ \advance \process_generation \thr@@
+ \edef\process_generation_succ{\the\process_generation}
+ \advance \process_generation \m@ne
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\gobble_five}
+% \begin{macrocode}
+\def\gobble_five#1#2#3#4#5{}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% It is appropriate that the map file writer writes a summary of the
+% kinds of risky things which happened when it is done writing data to
+% files. To simplify implementing such things, there is a command
+% \DescribeMacro{\includewarning}|\includewarning| that takes care of
+% the bookkeeping involved. After the call
+% \begin{quote}
+% |\includewarning|\meta{command}
+% \end{quote}
+% the \meta{command} will be executed exactly once the next time
+% |\reportwarnings| is executed. The \meta{command} usually expands to
+% something like
+% \begin{quote}
+% \small|\fontinstwarningnoline\mapfrags_subsystem{|\\
+% | Check~the~output~file(s)--some~data~was~considered~uncertain}|
+% \end{quote}
+%
+% \begin{macro}{\warnings_list}
+% The |\warnings_list| macro contains a list of all warnings that
+% should be made. It expands to a sequence of
+% \begin{quote}
+% |\warning_do|\meta{command}
+% \end{quote}
+% |\warnings_list| is always assigned globally.
+% \begin{macrocode}
+\g_let\warnings_list=\empty_command
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\includewarning}
+% \begin{macro}{\warning_do}
+% The |\includewarning| command adds an entry for its argument to the
+% |\warnings_list| list, provided there wasn't already such an entry.
+% |\includewarning| is based on the macro |\warning_do|, which does
+% most of the bookkeeping for making sure the list contains at most
+% one entry of each kind. |\warning_do| normally expects to be
+% expanded in the context
+% \begin{quote}
+% |\warning_do|\meta{new command}\meta{old command}\meta{next}
+% \end{quote}
+% The \meta{new command} is the command that is being added to the
+% list, and the \meta{old command} is a command that is already in the
+% list. \meta{next} is the first token in the next item in the
+% list---in most cases another |\warning_do|. If \meta{new command}
+% and \meta{old command} are not equal, this should expand to
+% \begin{quote}
+% |\noexpand\warning_do|\,|\noexpand|\meta{old command}\,^^A
+% \meta{next}\,\meta{new command}
+% \end{quote}
+% If on the other hand they are equal, this should expand to
+% \begin{quote}
+% |\noexpand\warning_do|\,|\noexpand|\meta{old command}\,^^A
+% \meta{next}\,|\x_relax|
+% \end{quote}
+% The reason for this is that the last \meta{next} will not be a
+% |\warning_do|, but an |\ifx| which tests whether a new item should
+% be added to the list.
+% \begin{macrocode}
+\def\warning_do#1#2#3{
+ \noexpand\warning_do \noexpand#2
+ \ifx #1#2
+ \expandafter#3 \expandafter\x_relax
+ \else
+ \expandafter#3 \expandafter#1
+ \fi
+}
+\def\includewarning#1{
+ \xdef\warnings_list{
+ \expandafter\swap_two \expandafter#1 \warnings_list
+ \if_equal\x_relax\then \else
+ \noexpand\warning_do \noexpand#1
+ \fi
+ }
+}
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+% \begin{macro}{\reportwarnings}
+% The |\reportwarnings| command reports all the warnings and empties
+% the |\warnings_list|.
+% \begin{macrocode}
+\def\reportwarnings{
+ \begingroup
+ \let\warning_do=\x_relax
+ \warnings_list
+ \endgroup
+ \g_let\warnings_list=\empty_command
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\warn_unknown_source}
+% \begin{macro}{\warn_undecided_data}
+% \begin{macro}{\warn_uncertain_data}
+% These macros are used to output warnings at the |\reportwarnings| at
+% the end of |\donedrivers|.
+% \begin{macrocode}
+\def\warn_unknown_source{
+ \fontinstwarningnoline\mapfrags_subsystem{
+ Some~font~is~missing~from~the~output~file(s),\messagebreak
+ since~its~source~is~unknown}
+}
+\def\warn_undecided_data{
+ \fontinstwarningnoline\mapfrags_subsystem{
+ Check~the~output~file(s)--some~data~could~not~be~determined}
+}
+\def\warn_uncertain_data{
+ \fontinstwarningnoline\mapfrags_subsystem{
+ Check~the~output~file(s)--some~data~was~considered~uncertain}
+}
+% \end{macrocode}
+% \end{macro}\end{macro}\end{macro}
+%
+%
+%
+% \subsubsection{Configuration interface}
+% \label{Sssec:Config-interface}
+%
+% To correctly format reencodings, the map file writer must know what
+% the ETX encodings correspond to. In the case of drivers which
+% generate postscript output, this information is stored in the
+% \describecsfamily{pse-\meta{etx}}|\pse-|\meta{etx} family of macros.
+% \meta{etx} is the name (suffix excluded) of the ETX file that the
+% information pertains to. The expansion of these macros are of the form
+% \begin{quote}
+% \marg{postscript name}\marg{action}
+% \end{quote}
+% \meta{postscript name} is the name by which the encoding is known to
+% the postscript interpreter, and \meta{action} lists any additional
+% action that must be taken before the encoding can be used. So far the
+% only action known is \DescribeMacro{\download}|\download|\marg{file},
+% which will cause code for downloading the file by the name \meta{file}
+% (suffix included) to be inserted in the output.
+%
+% \begin{macro}{\declarepsencoding}
+% Data is entered in a |\pse-|\meta{etx} macro using the
+% |\declare|\-|ps|\-|encoding| command. Its syntax is
+% \begin{quote}
+% |\declarepsencoding|\marg{etx}\marg{postscript name}\marg{action}
+% \end{quote}
+% \begin{macrocode}
+\def\declarepsencoding#1#2#3{\x_cs\gdef{pse-#1}{{#2}{#3}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\download}
+% By default |\download| gobbles its argument. It should be redefined
+% when that is not the desired effect.
+% \begin{macrocode}
+\let\download=\gobble_one
+% \end{macrocode}
+% \end{macro}
+%
+% Some encodings seem to always be present, so they can be declared here.
+% \begin{macrocode}
+\declarepsencoding{8r}{TeXBase1Encoding}{\download{8r.enc}}
+\declarepsencoding{8a}{StandardEncoding}{}
+% \end{macrocode}
+% \package{fontinst} must be told about other postscript encodings (if you
+% have them installed). The \texttt{finstmsc.rc} file is the right place
+% for these declarations.\relax
+% \SortIndex{finstmsc.rc file}{\texttt{finstmsc.rc} file}
+%
+% Next we have the cofiguration for fonts, which works in a similar
+% fashion. The main problem here seems to be to determine which files (if
+% any) should be downloaded to the printer, and this can be specified
+% using |\download| commands as for the encodings. The family
+% \describecsfamily{psf-\meta{PS font name}}|\psf-|\meta{PS font name}
+% of macros expand to a sequence of \meta{actions} as for the encodings.
+% If there is such a macro for a font then the instructions found there
+% should be followed.
+%
+% It is recommended that the contents of a |\psf-|\meta{PS font name}
+% macro is executed before the map file entry is written, and that
+% commands like |\download| are temporarily redefined to build the text
+% for the entry, rather than having the |\write| in |\pout_line| expand
+% the contents of |\psf-|\meta{PS font name}.
+%
+% \begin{macro}{\specifypsfont}
+% The |\specifypsfont| command is used as
+% \begin{quote}
+% |\specifypsfont|\marg{PS font name}\marg{actions}
+% \end{quote}
+% It can be used to specify the actions that should be done to make a
+% Postscript font known to the printer, when the automatic guessing
+% would not be right.
+% \begin{macrocode}
+\def\specifypsfont#1#2{\x_cs\def{psf-#1}{#2}}
+% \end{macrocode}
+% \end{macro}
+%
+% Examples of cases where |\specifypsfont| would be needed are:
+% \begin{itemize}
+% \item Fonts which are resident on the printer. In this case the
+% \meta{actions} argument should be empty, e.g.
+% \begin{quote}
+% |\specifypsfont{Times-Roman}{}|
+% \end{quote}
+% \item Instances of multiple master fonts. In this case one must
+% download both the multiple master font and the stub file that
+% defines the instance.
+%
+% Subsection~10.6.1 in The \LaTeX\ graphics companion~\cite
+% {LaTeX-graph-comp} contains an example with an instance of the
+% \texttt{MinionMM} multiple master font. Both the \TeX\ and
+% (what is of interest here) the PS name for this instance is
+% \texttt{zmnl8ac6}, the base multiple master font is stored in the
+% file \texttt{MinionMM.pfb}, and the stub file is called
+% \texttt{zmnl8ac6.pro}. The |\specifypsfont| command for this is
+% \begin{quote}
+% |\specifypsfont{zmnl8ac6}{%|\\
+% | \download{MinionMM.pfb}\download{zmnl8ac6.pro}%|\\
+% |}|
+% \end{quote}
+% \item Fonts which do not fit any of the general naming schemes.
+% \end{itemize}
+%
+%
+% \begin{macro}{\AssumeLWFN}
+% This command makes \mbox{MacOS} \texttt{LWFN} style abbreviated
+% Postscript font names the default for fonts that have no
+% |\psf-| entry.
+% \begin{macrocode}
+\def\AssumeLWFN{\let\get_PS_font_file\LWFN_get_PS_font_file}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \subsection{Deducing values for the map file entries}
+%
+%
+% \subsubsection{Basic principles}
+%
+% The automatic generation of map file fragments mainly consists of
+% determining various text strings and writing these to a file as the
+% format of the map file being written requires. The complicated part is
+% usually to determine what these text strings should be, since the only
+% restriction imposed by the output format often is that the strings
+% should be written in the right order and with separating whitespace.
+%
+% It is furthermore the case that some of these text strings seem to be
+% hard to deduce from the information primarily given in the command to
+% write the entry, but somewhat easier to deduce from some other deduced
+% text string.
+%
+% Therefore the following model seems appropriate. For each text string
+% that may need to be deduced, there is one macro which is used to store
+% the string (if it has been deduced) and one macro which can be called
+% to set the former macro to an appropriate value. Thus there is one
+% macro |\PS_font_name| which stores the postscript name for the font
+% currently in question and one macro
+% \describecsfamily{get_\meta{string name}}|\get_PS_font_name| which
+% determines the proper value for |\PS_font_name|. There is also a macro
+% \DescribeMacro{\unknown_str}|\unknown_str| to which all the
+% string storing macros should initially be |\let|, so that it can be
+% easily tested whether a string storing macro has been given its proper
+% value or not.
+%
+% Typically, if |\PS_font_name| is used somewhere, one would first have
+% a piece of code that says
+% \begin{quote}
+% \small
+% |\ifx\PS_font_name\unknown_str|\\
+% | \get_PS_font_name|\\
+% |\fi|
+% \end{quote}
+% to ensure that it is known when it is used.
+%
+% \begin{macro}{\unknown_str}
+% A suitable value for this macro seems to be |?????|.
+% \begin{macrocode}
+\def\unknown_str{?????}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\clueless_str}
+% To further support this model, there is also a macro |\clueless_str|
+% which a string storing macro should be |\let| equal to if its proper
+% value could not be determined. This distinction is useful for the
+% |\get_|\textellipsis\ macros, since if |\get_|$A$ can determine the
+% correct value of $A$ from $B$, but also from $C$, then it helps if
+% |\get_|$A$ can easily check whether it has previously turned out to
+% be impossible to determine the value of $B$, because then it can
+% simply deduce $A$ from $C$ instead.
+%
+% \begin{macrocode}
+\edef\clueless_str{\unknown_str ?}
+% \end{macrocode}
+% \end{macro}
+%
+% An example of how |\clueless_str| should be used is the following
+% skeleton of a |\get_|$A$ macro:
+% \begin{quote}\small
+% |\def\get_|$A$|{|\\
+% | \ifx\unknown_str\|$B$| \get_|$B$| \fi|\\
+% | \ifx\clueless_str\|$B$\\
+% | \ifx\unknown_str\|$C$| \get_|$C$| \fi|\\
+% | \ifx\clueless_str\|$C$\\
+% | \let\|$A$|\clueless_str|\\
+% | \else|\\
+% | |\meta{Deduce $A$ from $C$}\\
+% | \fi|\\
+% | \else|\\
+% | |\meta{Deduce $A$ from $B$}\\
+% | \fi|\\
+% |}|
+% \end{quote}
+%
+%
+% \subsubsection{Implementation}
+%
+% \begin{macro}{\TeX_font_name}
+% This is the name (as appearing in a DVI or VF file) of the font for
+% which an entry should be made. It is set by |\makemapentry|, so no
+% |\get_|\textellipsis\ macro is needed.
+% \begin{macrocode}
+\let\TeX_font_name\unknown_str
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\source_font_TeX_name}
+% This is the name (as AFM or PL) of the font whose metrics were
+% used by \package{fontinst}. It is set by |\fromafm| or |\frompl|,
+% so no |\get_|\textellipsis\ macro is needed.
+% \begin{macrocode}
+\let\source_font_TeX_name\unknown_str
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\PS_font_name}
+% This is the name (as FontName entry in an AFM or correspondingly) of
+% the font in question.
+% \begin{macrocode}
+\let\PS_font_name\unknown_str
+% \end{macrocode}
+% \begin{macro}{\get_PS_font_name}
+% I expect this to become one of the central macros in the map file
+% generation (at least when entries are generated for postscript
+% fonts), but for the moment it does the closest thing to nothing a
+% |\get_|\textellipsis\ macro is allowed to do; it admits it hasn't
+% got a clue about what the proper value is.
+% \begin{macrocode}
+\def\get_PS_font_name{\let\PS_font_name\clueless_str}
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+% \begin{macro}{\AssumeAMSBSYY}
+% \begin{macro}{\AssumeBaKoMa}
+% These commands redefine |\get_PS_font_name| so that it returns the
+% PS name this font would have if it was part of the AMS\slash
+% Blue~Sky\slash Y\&Y and BaKoMa respectively distribution of the
+% Computer Modern fonts---the \TeX\ font name in all upper case and
+% all lower case respectively.
+% \begin{macrocode}
+\def\AssumeAMSBSYY{\def\get_PS_font_name{
+ \uppercase \expandafter{ \expandafter\def
+ \expandafter\PS_font_name \expandafter{ \source_font_TeX_name}
+ }
+}}
+% \end{macrocode}
+% \begin{macrocode}
+\def\AssumeBaKoMa{\def\get_PS_font_name{
+ \lowercase \expandafter{ \expandafter\def
+ \expandafter\PS_font_name \expandafter{ \source_font_TeX_name}
+ }
+}}
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+%
+% \begin{macro}{\PS_font_file}
+% This is the name of the file (suffix included) in which the PS font
+% is expected to be found.
+% \begin{macrocode}
+\let\PS_font_file\unknown_str
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\get_PS_font_file}
+% \begin{macro}{\normal_get_PS_font_file}
+% \begin{fistring}{PSfontsuffix}
+% The macro |\normal_get_PS_font_file| is (hardly surprisingly) the
+% normal |\get_PS_font_file|. It simply uses |\source_font_TeX_name|
+% plus the suffix specified by the |PSfontsuffix| string.
+% \begin{macrocode}
+\resetstr{PSfontsuffix}{.pfa}
+\def\normal_get_PS_font_file{
+ \edef\PS_font_file{\source_font_TeX_name\str{PSfontsuffix}}
+}
+\let\get_PS_font_file=\normal_get_PS_font_file
+% \end{macrocode}
+% \end{fistring}\end{macro}\end{macro}
+%
+% \begin{macro}{\LWFN_get_PS_font_file}
+% \begin{macro}{\abbreviate_PS_font_name}
+% In MacOS, Postscript fonts file names are usually abbreviated forms of
+% the Postscript font names, formed using the so called
+% \(5+3+3+\cdots\) rule---keep the first five letters of the first
+% subword, keep the first three letters of all following subwords. The
+% |\LWFN_get_PS_font_file| macro uses this scheme if the Postscript
+% name for the font is known, otherwise it calls the
+% |\normal_get_PS_font_file|. The LWFN in the macro name is the type
+% code for such files.
+%
+% The algorithm is based on using |\aftergroup| to construct the
+% wanted |\def| statement, only |\aftergroup|ing the letters that are
+% not to be removed in the abbreviation. |\a_count| is used as a
+% counter of how many more letters in the current subword should be
+% kept.
+% \begin{macrocode}
+\def\LWFN_get_PS_font_file{
+ \ifx \PS_font_name\unknown_str \get_PS_font_name \fi
+ \ifx \PS_font_name\clueless_str
+ \normal_get_PS_font_file
+ \includewarning\warn_uncertain_data
+ \else
+ \begingroup
+ \aftergroup\def \aftergroup\PS_font_file
+ \aftergroup{
+ \a_count=4~
+ \expandafter\expandafter \expandafter\aftergroup
+ \expandafter\swap_two \expandafter\abbreviate_PS_font_name
+ \PS_font_name \x_relax
+ \aftergroup}
+ \endgroup
+ \fi
+}
+% \end{macrocode}
+% \begin{macrocode}
+\def\abbreviate_PS_font_name#1{
+ \ifx \x_relax#1 \else
+ \ifnum \uccode`#1=`#1
+ \a_count=2
+ \aftergroup#1
+ \else\ifx -#1
+ \a_count=\z@
+ \else\ifnum \a_count>\z@
+ \advance \a_count \m@ne
+ \aftergroup#1
+ \fi\fi\fi
+ \expandafter\abbreviate_PS_font_name
+ \fi
+}
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+%
+%
+% \subsection{Driver makers}
+%
+% This subsection contains the definitions of macros that makes up the
+% driver makers.
+%
+%
+% \subsubsection{The \texttt{debug} driver}
+%
+% The \texttt{debug} driver maker doesn't really generate entries for
+% any DVI driver map file, it just prints the data that was available.
+% It is mainly intended for debugging purposes, but it might also serve
+% as a basic model for other driver makers.
+%
+% \begin{macro}{\make_debug}
+% \begin{macrocode}
+\def\make_debug{
+ \pout_line\output_debug{Driver~data~for~font~\TeX_font_name:}
+ \pout_lline\output_debug{Source~font~TeX~name:~\source_font_TeX_name}
+ \ifx \reencode_etx\empty_command \else
+ \pout_lline\output_debug{Font~reencoded~using~\reencode_etx.etx.}
+ \fi
+ \ifdim \xscale_factor=\p@ \else
+ \pout_lline\output_debug{Font~x-scaled~by~
+ \expandafter\lose_measure\the\xscale_factor.
+ }
+ \fi
+ \ifdim \slant_factor=\z@ \else
+ \pout_lline\output_debug{Font~slanted~by~
+ \expandafter\lose_measure\the\slant_factor.
+ }
+ \fi
+ \debug_values_hook
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\debug_value}
+% The |\debug_value| macro can be used to print the name and contents
+% of an arbitrary value macro in the |debug| driver. It is called with
+% the value macro as argument, e.g.
+% \begin{quote}
+% |\debug_value\PS_font_name|
+% \end{quote}
+%
+% \begin{macrocode}
+\def\debug_value#1{
+ \ifx #1\unknown_str
+ \csname get_ \expandafter\gobble_one \string#1 \endcsname
+ \fi
+ \pout_lline\output_debug{\string#1:~#1}
+ \ifx #1\clueless_str \includewarning\warn_undecided_data \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\debugvalue}
+% \begin{macro}{\debug_values_hook}
+% The |\debugvalue| command is a user level interface for adding
+% value macros to the list of those that are displayed by the
+% \texttt{debug} driver. The argument is the name of the value in
+% question, e.g.
+% \begin{quote}
+% |\debugvalue{PS_font_name}|
+% \end{quote}
+% Note that the name given to |\debugvalue| is not the control
+% sequence in which the name is stored.
+% \begin{macrocode}
+\def\debugvalue#1{
+ \expandafter\add_to \expandafter\debug_values_hook
+ \expandafter{ \expandafter\debug_value \csname#1\endcsname}
+}
+% \end{macrocode}
+% \begin{macrocode}
+\let\debug_values_hook\empty_command
+\debugvalue{PS_font_name}
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+%
+% \subsubsection{The \texttt{dvips} driver}
+%
+% \changes{1.912}{2000/02/19}{\texttt{dvips} mapfile fragments writer
+% added. (LH)}
+% Before constructing an entry for a \package{dvips} mapfile, it should
+% be sorted out how such an entry should look. The \package{dvips}
+% manual says
+% \begin{quotation}
+% The parsing of the \texttt{psfonts.map} file should be explained to
+% eliminate all confusion. If a line is empty or begins with a space,
+% asterisk, semicolon, or hash mark, it is ignored. Each remaining
+% line is separated into words, where words are separated by spaces or
+% tabs. If a word begins with a double quote, it extends until the
+% next double quote or the end of the line. If a word starts with a
+% less than character, it is treated as a font header file (or a
+% downloaded PostScript font). There can be more than one such header
+% for a given font. If a word starts with a double quote, it is a
+% special instruction for generating that font. Otherwise it is a
+% name. The first such name is always the name \TeX\ uses for the
+% font and is also the name of the raw \texttt{tfm} file. If there is
+% another name word, that name is used as the PostScript name; if
+% there is only one name word, it is used for both the \TeX\ name and
+% the PostScript name.
+% \end{quotation}
+%
+% A \package{fontinst}-generated map file entry for the \texttt{dvips}
+% driver has the following structure:
+% \begin{isyntax}
+% \meta{\TeX{} font name} \meta{PS font name} \meta{downloads}
+% \meta{font transformations}
+% \end{isyntax}
+% \meta{\TeX{} font name} is simply the value of |\TeX_font_name| and
+% \meta{PS font name} is simply the value of |\PS_font_name|.
+% \meta{downloads} is a possibly empty sequence in which each item
+% has the form
+% \begin{quote}
+% \meta{prefix}\meta{filename}
+% \end{quote}
+% The \meta{prefix} values I've came across are empty,\footnote{I think
+% this is only used for files that \package{dvips} should ignore, but
+% which certain other programs that read the same \texttt{psfonts.map}
+% need.} |<|, |<<|, and |<[|. Currently |<| is always used.
+% \meta{filename} is a filename with suffix. \meta{font transformations}
+% is either empty or has the form
+% \begin{quote}
+% |"| \meta{Postscript code} |"|
+% \end{quote}
+%
+% Should support for the |<<| or |<[| prefixes be needed, then this
+% should be done by adding some new variant of the |\download|
+% command---|\fullldownload|, maybe---rather than adding the extra
+% character to the \meta{filename}. To simplify matters for other drivers,
+% such new variants should by default expand to |\download|, rather than
+% |\gobble_one|.
+%
+%
+% \begin{macro}{\downloads_list}
+% \begin{macro}{\append_download}
+% The |\downloads_list| is a token list register which is especially
+% used for accumulating |\download| commands. Each driver maker which
+% uses it should begin by emptying it.
+% \begin{quote}
+% |\append_download|\marg{arg}
+% \end{quote}
+% appends
+% \begin{quote}
+% |\download|\marg{arg}
+% \end{quote}
+% to |\downloads_list|.
+% \begin{macrocode}
+\newtoks\downloads_list
+\def\append_download#1{
+ \downloads_list=\expandafter{ \the\downloads_list \download{#1} }
+}
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+%
+% \begin{macro}{\make_dvips}
+% This macro gathers the information for a \texttt{dvips} driver entry
+% and writes it to the corresponding output file. As a \texttt{dvips}
+% mapfile entry is on one line, the entire entry is written at once.
+% The \meta{font transformations} is collected as explicit text in the
+% macro |\postscript_code|. The \meta{downloads} is collected as a
+% sequence of |\download| commands in the |\downloads_list| token
+% register.
+% \begin{macrocode}
+\def\make_dvips{
+ \downloads_list={}
+ \let\postscript_code\empty_command
+ \let\download\append_download
+ \ifx \reencode_etx\empty_command \else
+ \if_undefined{pse-\reencode_etx}\then
+ \etxtoenc{\reencode_etx}{\reencode_etx}
+ \fi
+ \expandafter\expandafter \expandafter\second_of_two
+ \csname pse-\reencode_etx\endcsname
+ \edef\postscript_code{\postscript_code\space
+ \expandafter\expandafter \expandafter\first_of_two
+ \csname pse-\reencode_etx\endcsname
+ \space ReEncodeFont
+ }
+ \fi
+ \ifdim \xscale_factor=\p@ \else
+ \edef\postscript_code{\postscript_code
+ \space\expandafter\lose_measure\the\xscale_factor
+ \space ExtendFont
+ }
+ \fi
+ \ifdim \slant_factor=\z@ \else
+ \edef\postscript_code{\postscript_code
+ \space\expandafter\lose_measure\the\slant_factor
+ \space SlantFont
+ }
+ \fi
+% \end{macrocode}
+% After constructing the \meta{Postscript code} and having appended
+% the necessary download (if any) for that code, the next problem is
+% to determine the actual \meta{PS font name} and append the downloads
+% needed to actually define the font to the Postscript interpreter. If
+% there is no special entry for this font in the |\psf-|\meta{PS font
+% name} table, or if its \meta{PS font name} is unknown, then it is
+% assumed that exactly one file should be downloaded. As the name of
+% that file is taken the value of |\PS_font_file|.
+% \begin{macrocode}
+ \ifx \PS_font_name\unknown_str \get_PS_font_name \fi
+ \ifx \PS_font_name\clueless_str
+ \includewarning\warn_undecided_data
+ \_a_true
+ \else
+ \if_undefined{psf-\PS_font_name}\then
+ \_a_true
+ \else
+ \csname psf-\PS_font_name \endcsname
+ \_a_false
+ \fi\fi
+ \if_a_
+ \ifx \PS_font_file\unknown_str \get_PS_font_file \fi
+ \append_download{\PS_font_file}
+ \ifx \PS_font_file\clueless_str
+ \includewarning\warn_undecided_data
+ \fi
+ \fi
+% \end{macrocode}
+% Finally, the entire entry is written to the file. The point with
+% expanding past an empty command is that \TeX\ in a |\write| normally
+% jumps past the expansion of a |\the|\meta{token list register}
+% without expanding it further, but this effect can be prevented by
+% expanding the |\the| with an |\expandafter|.
+% \begin{macrocode}
+ \def\download##1{~<##1}
+ \pout_line\output_dvips{
+ \TeX_font_name\space\PS_font_name
+ \expandafter\empty_command \the\downloads_list
+ \ifx \postscript_code\empty_command \else
+ \space"\postscript_code\space"
+ \fi
+ }
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \subsubsection{The \texttt{dvipdfm} driver}
+%
+% \changes{1.912}{2000/02/22}{\texttt{dvipdfm} mapfile fragments writer
+% added. (LH)}
+%
+% A mapfile entry for the \texttt{dvipdfm} driver has the following
+% structure:
+% \begin{isyntax}
+% \meta{\TeX{} font name} \meta{encoding} \meta{PS font}
+% \meta{options}
+% \end{isyntax}
+% \meta{\TeX{} font name} is simply the value of |\TeX_font_name|.
+% \meta{encoding} is the name of the encoding file which should be used
+% to reencode the font, or \texttt{default} if there is none. \meta{PS
+% font} is the value of |\PS_font_name| for the standard 35 fonts
+% (i.e., fonts which will not be included in the PDF generated), but for
+% other fonts it is the name of the file which contains the
+% font.\footnote{The documentation seems to say that \texttt{dvipdfm}
+% can only understand fonts in PFB format; I have chosen to ignore this
+% potential problem.} \meta{options}, finally, is a possibly empty
+% sequence of space-separated options. Each option is one of the
+% following
+% \begin{quote}
+% |-e |\meta{number}\\
+% |-s |\meta{number}\\
+% |-r|
+% \end{quote}
+% The |-e| and |-s| options extend and slant by the given amounts. The
+% |-r| option is a workaround for some Acrobat bugs; it is currently not
+% generated by \package{fontinst}.
+%
+% \begin{macro}{\make_dvipdfm}
+% This macro gathers the information for a \texttt{dvipdfm} driver entry
+% and writes it to the corresponding output file. As a \texttt{dvipdfm}
+% mapfile entry is on one line, the entire entry is written at once.
+% The \meta{options} text is collected as explicit text in the
+% macro |\options_text|. The \meta{downloads} is collected as a
+% sequence of |\download| commands in the |\downloads_list| token
+% register.
+% \begin{macrocode}
+\def\make_dvipdfm{
+ \def\font_encoding{default}
+ \ifx \reencode_etx\empty_command \else
+ \if_undefined{pse-\reencode_etx}\then
+ \etxtoenc{\reencode_etx}{\reencode_etx}
+ \fi
+ \def\download##1{\def\font_encoding{##1}}
+ \expandafter\expandafter \expandafter\second_of_two
+ \csname pse-\reencode_etx\endcsname
+ \fi
+ \let\options_text\empty_command
+ \ifdim \xscale_factor=\p@ \else
+ \edef\options_text{\options_text\space
+ -e~\expandafter\lose_measure\the\xscale_factor
+ }
+ \fi
+ \ifdim \slant_factor=\z@ \else
+ \edef\options_text{\options_text\space
+ -s~\expandafter\lose_measure\the\slant_factor
+ }
+ \fi
+% \end{macrocode}
+% After constructing the \meta{options} and having determined
+% \meta{encoding}, the next problem is to determine the actual
+% \meta{PS font}, which will be put in |\a_macro|. If there is no
+% special entry for this font in the |\psf-|\meta{PS font name} table,
+% or if its \meta{PS font name} is unknown, then it is assumed that
+% exactly one file should be downloaded. As the name of that file is
+% taken the value of |\PS_font_file|.
+% \begin{macrocode}
+ \ifx \PS_font_name\unknown_str \get_PS_font_name \fi
+ \if_or \if_equal\PS_font_name\clueless_str \or_else
+ \if_undefined{psf-\PS_font_name}
+ \then
+ \ifx \PS_font_file\unknown_str \get_PS_font_file \fi
+ \ifx \PS_font_file\clueless_str
+ \includewarning\warn_undecided_data
+ \fi
+ \let\a_macro=\PS_font_file
+ \else
+ \let\a_macro=\PS_font_name
+ \def\download##1{\def\a_macro{##1}}
+ \csname psf-\PS_font_name \endcsname
+ \fi
+% \end{macrocode}
+% Finally, the entire entry is written to the file.
+% \begin{macrocode}
+ \pout_line\output_dvipdfm{
+ \TeX_font_name\space\font_encoding\space\a_macro
+ \options_text
+ }
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsubsection{The \texttt{pltotf} ``driver''}
+% \changes{1.915}{2000/06/27}{\texttt{pltotf} ``driver'' support
+% added. (LH)}
+%
+% It can sometimes be hard to determine which of all the PL files that
+% \package{fontinst} creates need to be converted to TFM files. In most
+% cases no \texttt{8a}-encoded PLs need to be converted as they aren't
+% used as base fonts or installed in an FD file, but to automatically
+% exclude them isn't a trivial task (even though it probably could be
+% done by a regular expression filter for fonts named according to the
+% \texttt{fontname} scheme). There furthermore seems to be some systems
+% on which it for various reasons isn't easy to convert all PLs in a
+% directory. The \texttt{pltotf} ``driver'' support is meant to help with
+% both these problems, as the ``map file'' it creates really is a shell
+% script (batch file) for converting precisely those PL files that need
+% a map file entry to TFM format. I believe the shell script will work
+% both for UNIX and DOS systems.
+%
+% \begin{macro}{\make_pltotf}
+% \begin{fistring}{TFMfileprefix}
+% |\make_pltotf| writes a \package{PLtoTF} command for converting the
+% current font's PL file to a TFM file. If set, the string
+% \texttt{TFMfileprefix} will be prepended to the TFM file name---this
+% could be used for putting the TFMs in some directory other than the
+% current.
+% \begin{macrocode}
+\def\make_pltotf{
+ \pout_line\output_pltotf{pltotf~\TeX_font_name.pl~
+ \ifisstr{TFMfileprefix}\then \str{TFMfileprefix}\fi
+ \TeX_font_name.tfm
+ }
+}
+% \end{macrocode}
+% \end{fistring}\end{macro}
+%
+%
+% \begin{macrocode}
+%</map>
+% \end{macrocode}
+% \Finale
+\endinput
+