[Fontinst] The fontinst manual

[Lars Hellström]

Hello, all.

As part of getting fontinst updated, I though I should also have a go at
updating the manual (which has been mostly neglected since the major
overhaul in 1998). There are quite a lot of commands which have been added
since then, and there should be some source of information about them that
is more accessible than the *.dtx files.

Alas, this turned out to not be that easy; that there are commands missing
is not the only problem with the manual, and I'm not at all sure what would
be the best way to proceed with it. This mail is rather much my "thinking
loud about the problem", and should anyone have any suggestions then feel
free to join in.

So far I've mostly looked at the "Introduction" section (got stuck already
there). Some stuff there definitely is wrong and should be changed. For
example, it is suggested that one does

  setenv TEXINPUTS $TEXMF/fonts/afm//::

to give fontinst access to AFM files in the TEXMF tree. Nowadays this will
probably not work, because kpathsea is most often configured via its own
set of variables, meaning in particular that there is no TEXMF environment
variable for the shell to expand. What would work (I even tried it) is to
write

  setenv TEXINPUTS \$TEXMF/fonts/afm//::

since this quotes the $ in the shell, preserving the $TEXMF for kpathsea to
resolve. So: It's easy to fix, but also rather fragile. (For one, it
assumes environment variables are set using setenv, which is not the case
in bash.) Should it then be mentioned at all?

Another item is that the manual says AFM metric files like

  fonts/psfonts/adobeafm/base35/tib_____.afm

can be found on CTAN. This hasn't been the case for quite a lot of years
now. Several remarks look very antiquated; the processing time reference is
"a 40~MHz 80486SX PC or a 25~MHz 68LC040 Macintosh".

At the same time, I find it difficult to change the text. It is written
rather much from Rowland's perspective (often apparent in the use of first
person singular pronouns: I, me, my; which is curiously looking in a text
with two authors), and following that style doesn't feel right. OTOH
getting rid of that style would probably require a thorough rewrite.

So, what to do?

The quick thing would be to slap a warning label "This is old and not up to
date" on the manual, with a reference to fisource.dvi for information about
new features. In view of TeXLive production schedules, I suspect I will do
this. But there is also the long run to think about.

One thing that could be done would be to split off the first two sections
from the manual and name that `intro98' or some such. Then the errors
wouldn't be quite as bad.

Those two sections are also rather tutorial-like. I vaguely recall some
more recent tutorial being referred to. Is that something that
could/should/might be included with the main fontinst distribution?

Another way to reorganise things would be to have a manual that is
organised after features and problems, while moving the more
specification-like material (e.g. "An <integer expression> is one of the
following:" and all that stuff) to a separate file, probably fisource.tex.
This would probably make it more likely that I keep it up to date, but it
could also make it less accessible.


Hmmm... That seems to be it, for now. But feel free to join in with the
discussion.

Lars Hellström