[Fontinst] The fontinst manual

[Philipp Lehman]

Am Sonntag, 25. Juli 2004 17:56 schrieb Lars Hellström:

> 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).

Hey, more power to you!

I have a couple of remarks, based on my experiences with writing and 
maintaining the Font installation guide and the feedback I received from 
users.

> setenv TEXINPUTS $TEXMF/fonts/afm//::
> Should it then be mentioned at all?

I wonder if you should be bothered with the basic setup at all. This stuff 
should work out of the box anyway. If something as basic as TEXINPUTS is not 
set correctly by a given Tex distribution, that distribution has a serious 
problem.

> 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?

Frankly, there are a lot of things in the introduction which you could 
probably remove from the manual entirely. At the end of the day, a rewrite 
might be easier than going over each paragraph individually.

> 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.

That's advisable in any case. The current situation is very confusing.

> 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.

Yes, but the question still remains why users should be bothered with obsolete 
material. If something is clearly obsolete, plain wrong, or not applicable 
any more, why keep it around at all?

> 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?

Not sure which tutorial you are referring too. I wrote a rather lengthy one:

http://www.ctan.org/tex-archive/info/Type1fonts/fontinstallationguide/

> 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.

I guess the most fundamental question is if you want the manual to be a 
tutorial or rather a reference manual. The current version of the manual 
tries to do both and I don't think this approach works out very well.

As a tutorial, it's a) too abstract and b) rather confusing because you don't 
really get the big picture. As a reference manual it's ok but poorly 
organized. Whenever I'm looking up a specific macro, I miss an index and a 
fine-grained TOC which lists all macros so that I can quickly jump to the 
relevant part of the manual.

My experience is that, in order to use fontinst in a productive way, you need 
both a tutorial and a reference manual. Having to go over all the macros 
individually before getting down to business is very discouraging. On the 
other hand, a tutorial is no substitute for a comprehensive command reference 
and everybody will need that at some point.

-- 
Philipp Lehman <lehman at gmx.net>