[Fontinst] The fontinst manual

[Lars Hellström]

At 16.58 +0200 04-07-26, Philipp Lehman wrote:
>Am Sonntag, 25. Juli 2004 17:56 schrieb Lars Hellström:
>
>
>> 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?

Well, most of it is not "plain wrong" but rather "something I do not feel I
can anser for". (The TEXINPUTS example, which is the only truly technical
error I've spotted, was the same as in Alan's 1996 v1.504 manual, and it
doesn't seem that anyone has been troubled by it in those 8 years.)

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

Nor was I.

>I wrote a rather lengthy one:
>
>http://www.ctan.org/tex-archive/info/Type1fonts/fontinstallationguide/

Very nice! Very, very nice! (Red ink as second colour; I like that. Much
better than the blue used in The LaTeX Companion. But why "Tex" rather than
the standard \TeX? The name of the program is <Tau><Epsilon><Chi>, and I'm
pretty sure lower case epsilons don't look like that "e".)

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

I generally prefer the latter (regardless of language), but I'm probably
abnormal.

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

Actually, I find it a bit thin as a reference manual, but I'm not quite
sure why. Possibly manu things are glossed over.

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

As for index and such, have you tried using fisource.dvi? (It's hard to get
a more fine-grained index than that.) If so, what are your experiences of
that? (Some commands have rather detailed descriptions in the source.)

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

Agreed.

At 07.40 +0200 04-07-26, Ulrich Dirr wrote:
>
>I would like to have a manual with an introduction explaining how fontinst
>works in general. Here there should also be explained how everything is
>organized in respect to texmf and in respect of mtx/etx/whatever. And maybe
>how an installation of fonts works in general (probably there could be
>borrowed something from the excellent font installation guide by Philipp
>Lehman).

"Borrowing" is always a bit problematic (copyright-wise, if nothing else).
Then it is probably better to let that guide stand for itself and refer to
it. In comparison, noone expects the LaTeX usrguide.tex to be a tutorial;
rather one would point to "The not so Short Introduction to LaTeX" for that.

>The easiest way to maintain the manual then would be to have a
>alphabetically sorted list of commands with descriptions what they are for
>and how they work, maybe be with a short example. Of course there should be
>a mark to which kind of file (general, mtx, etx) the command belongs.
>(There could be a summary chapter with just a listing of commands organized
>by file type.)

This sounds more like an overgrown "reference card" rather than a manual.

>Of course this reflects my personal taste. My biggest problems with
>fontinst are (1) to get the overall picture correct when trying to install
>a new font family, and (2) to find all the commands I needed.

It doesn't seem like an alphabetically sorted list of commands would be of
much help with either.

At 19.16 +0200 04-07-26, Walter Schmidt wrote:
>On Mon, 26 Jul 2004 16:58:07 +0200, Philipp Lehman wrote:
>
>>My experience is that, in order to use fontinst in a productive way, you
>>need
>>both a tutorial and a reference manual.
>
>ACK
>
>Why not regard the existing "fontinstallationguide" as the tutorial?
>Thus, Lars would have to re-write only ;-) the reference manual.

Yes, I'm leaning somewhat towards that.

At 20.41 +0200 04-07-26, Philipp Lehman wrote:
>Am Montag, 26. Juli 2004 18:35 schrieb Walter Schmidt:
>
>> I doubt that the path to the AFM files is normally part of the
>> TeX input path!
>
>Don't be too sure of that. Current Tetex has this in texmf.cnf:
>
>> % Fontinst needs to read afm files.
>> TEXINPUTS.fontinst = .;$TEXMF/tex//;$TEXMF/fonts/afm//
>
>Unless I'm getting something wrong that requires calling kpathsea with
>"--format fontinst" though, so it will not really work in practice ;)

FWIW, I think Tetex has a "fontinst" script which mostly boils down to

 tex -progname=fontinst \&tex ${1+"$@"}

This would make use of the above setting.


Thanks for all the input.

Lars Hellström