summaryrefslogtreecommitdiff
path: root/systems/unix/tex-fpc/README
blob: b22791869961237d5e8be772acfc55cec8b74a7e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
TeX-FPC, second edition, 2020-11-24

This directory contains change files for Donald E. Knuth's suite
of TeX related programs. The change files (.ch) and Don Knuth's WEB
files (.web) from January 2014 are the key components of a construction
kit for "TeX-FPC"---a complete TeX system based on the Free Pascal
Compiler (FPC), and running in any Unix environment.

These building bricks are glued together by shell scripts in
the---guess where---shell subdirectory.

The file tex-fpc.pdf shows how and why TeX-FPC differs from the original.
It was produced by two command lines:
   $ wve tex.web tex.ch
   $ dvipdf tex.dvi

The MFT directory contains shell scripts to create fonts (xxxfonts).
Its subdirectory iby shows how to add a font to TeX-FPC. In this
case a polytonic Greek font, suited for ancient Greek texts.

The directories dvips and xdvi help to get, compile and install Tom
Rokicki's dvips and Paul Vojta's xdvi.

Likewise the directory mp for John Hobby's METAPOST.

The directory tech demonstrates how to build a TeX system that
supports the german language.

And the ch.ch directory contains change files for change files.

Requirements:
============
TeX-FPC is liberal in what it accepts:
You will succeed with any flavor of the Unix operating system.
In fact, I only used stuff from:
   Kernighan, Pike: The Unix programming environment (1984) 
I have to admit, now and then I used vi instead of ed, the Unix Standard
Editor.
If it doesn't work on your system, it is not Unix, not even remotely so.

Any version of (FPC) from 3.0.0 on will suffice. To compile TeX and
METAFONT, three additional units are needed:
SysUtils, BaseUnix, Unix
They have to be specified on the command line:
    $ fpc -Fasysutils,baseunix,unix

To build the DVI-driver xdvi and dvips a C-compiler is necessary.
To run xdvi, you need X-Window and to print your books, you either
need a postscript printer or you use ghostscript to translate
postscript to your printers language.

Everything you need existed in the mid eighties of the last century.
All the great books produced with TeX demonstrates how much can be
done with how little.

Overview:
=========

File formats and their documentation:
-------------------------------------
WEB files:
.web	WEB programs, "The WEB System of Structured Documentation" (webman.tex)
.ch	Change files for WEB programs (patches to be applied to .web files)
.p	Pascal source
.pool   String pool, contains the string constants of a WEB program.


METAFONT files:
.mf	METAFONT source, "The METAFONTbook" (mfbook.tex)
.base   Base file, a compact representation of METAFONT's memory.
.tfm    TeX font metric, "TeX: The Program" (tex.web) part 30
.nnngf	generic font file, "METAFONT: The Program" (mf.web), part 46
.nnnpk	packed font file, gftopk.web, modules 21-36
        The last two are bitmap font formats, where nnn is a number that
        stands for "dots per inch". The number equals resolution of the
        output device as specified in your mode times the magnification.
.log    a log file
 
TeX files:
.tex	TeX source, "The TeXbook" (texbook.tex)
.fmt    Format file, a compact representation of TeX's memory.
        contains the string pool (tex.pool) and fifty .tfm files.
.dvi	device independent file, "TeX: The Program" (tex.web), part 31
.log    a log file

Dependencies of files and programs:
File		depends on
----		----------
xxx		xxx.p
xxx.p		xxx.web, xxx.ch
tex.pool	strings in tex.web or tex.ch
plain.fmt	plain.tex
		.tfm files (cf. plain.log)
		hyphen.tex
		tex.pool
mf.pool		strings in mf.web or mf.ch
plain.base	plain.mf
		local.mf
		mf.pool

Program		depends on
-------		----------
initex		TeXformats/tex.pool
tex		TeXformats/tex.fmt
inimf		MFbases/mf.pool
mf		MFbases/plain.base

Files and their processors:
--------------------------
WEB:
		   tangle
     x.web, x.ch --------> x.p, x.pool

                   fpc
             x.p  --------> x

                   tgl
      x.web, x.ch --------> x   (combines the last two steps, no pool)

                   itgl
      x.web, x.ch --------> inix.p, inix, x.pool (like tgl, but with pool)

		   weave
       .web, .ch --------> .tex (description of the program)

		   wve
       .web, .ch --------> .dvi (linking the above step and tex)


METAFONT:
                              inimf
  mf.pool, local.mf plain.mf --------> plain.base

                              mf
             plain.base, .mf --------> .nnngf, .tfm

                              gftopk
                      .nnngf --------> .nnnpk

                              mkfont
                         .mf --------> TeXfonts/.tfm, PKfonts/.nnnpk

                              mkpkfont
                         .mf --------> PKfonts/.nnnpk


TeX:
		                         initex
 tex.pool, hyphen.tex, plain.tex, .tfm  --------> plain.fmt

                                         tex
                  plain.fmt, .tfm, .tex --------> .dvi

DVI drivers:
                     dvips
 .tfm, .nnnpk, .dvi --------> .ps, PostScript printer

                     xdvi
 .tfm, .nnnpk, .dvi --------> X-Window


File names:
-----------
TeX-FPC searches files in directories which are local to the working
directory:
	TeXinputs  .tex
	TeXfonts   .tfm
	TeXformats .pool, .fmt
	MFinputs   .mf
	MFbases    .pool, .base
	PKfonts    .nnnpk
	DVIPSconf  .pro, .ps, .map (Header and configuration files for dvips)

Create one set of "master directories" and used symbolic links
to your working directory like:

	ln -s ~/TeXformats .

The scripts mk_TeX_dir and mk_MF_dir help to prepare a directory
for running TeX resp. METAFONT.  Adapt these scripts to the locations
of your master directories.

TeX-FPC's path searching applies to file names without directory
components, i.e. without a /:
	.tex	    local directory and then TeXinputs 
	.mf         local directory and then MFinputs
	.tfm        local directory and the TeXfonts
        .fmt        local directory and then TeXformats
         plain.fmt  hard coded (!) TeXformats/plain.fmt
        .base       local directory and MFbases
         plain.base hard coded (!) MFbases/plain.base
        .pool       hard coded (!) in TeXformats, MFbases 

Depending on the context, TeX-FPC programs append ".mf", ".tex", ".fmt",
".base" or ".tfm" to file names without extensions.

Fonts in TeX-FPC:
----------------
For each font, TeX needs one .tfm file. For each font and
resolution/magnification the DVI drivers need one .nnnpk file.
The script mkfont will install both a .tfm and an .nnnpk file, the
script mkpkfont will install an .nnnpk file only.  You specify the
resolution in your METAFONT mode and the magnification as an optional
second argument to mkpkfont or mkfont.  The DVI drivers will invoke
mkpkfont automatically to create missing .nnnpk files.

Running TeX-FPC
===============
Missing files
-------------
Search missing macro files like webmac.tex in Knuth's lib
directory and copy them to the working directory or to TeXinputs.
The .ch files import webmac-fpc.tex; move it to TeXinputs.

Search the sources of missing fonts in the lib directory (.mf),
copy them to MFinputs and use the scripts mkfont  or mkpkfont to
create and install .tfm files respective .pk files. The shell scripts
assume the METAFONT mode localfont which is defined in MFT/local.mf.
Remember, you've loaded local.mf into the file plain.base. Or you
might want to grep for font assignments in your .tex files. The
command line
	grep '\\font.*=' plain.tex > plainfonts
creates a list of the font names used by plain.tex. I edited
plainfonts to convert it to a shell script that creates all fonts
of the plain format. In the MFT directory you'll find other examples.
If the generation of a font failed, the failing command is written
to the file trouble in the working directory. You might want to fix the
error and rerun the file trouble, (sh trouble).

Installing new fonts from CTAN
------------------------------
The directory MFT/iby contains instructions on how to install a font
from CTAN, in this case ibygrk to typeset polytonic ancient Greek.

Printing the web-programs
-------------------------
The weave program generates an xxx.tex file from an xxx.web file
and a xxx.ch file. Use tex to generate an xxx.dvi file. This is
done by the script wve. For example, to view the description of
TeX-FPC, use
	wve tex.web tex.ch && xdvi tex
The web-macros need another font. Run MFT/webfonts to install it.
And run MFT/mfwebfonts for mf.tex.
The file tex-fpc.pdf provides the doc independent of an installed
TeX system. It describes how I adopted TeX to FPC, the features and
and differences of TeX-FPC.

TRIP TRAP
---------
Both tests are passed by TeX-FPC. See the trip and the trap directories..

Hints to build and install TeX-FPC from Knuth's sources.
========================================================

Get Knuth's source files:
------------------------
Get Knuth's distribution from
	ftp://ftp.dante.de/pub/tex/systems/knuth/dist.zip
At the DANTE server, passive ftp mode does not work. Try
	tug.org/tex-archive/systems/knuth
or      ftp ftp.cs.stanford.edu/tex/dist

This gives you the WEB files, manuals, macros and some .mf files.
At least you need the subdirectories lib, tex, mfware, mf and web.

You need another set of source files, namely the METAFONT source
files (.mf) for Knuth's font Computer Modern.

Copy the .mf files from
	ftp://ftp.dante.de/pub/tex/fonts/cm/mf/
or      ftp.cs.stanford.edu/tex/fonts/
to MFinputs.

And copy the .mf files from the lib directory to MFinputs.
        cp -p lib/*.mf MFinputs

All path names are given relative to directories of Knuth's distribution.

Building from WEB sources, (xxx.web and xxx.ch --> xxx, xxx.pool)
----------------------------------------------------------------
The general procedure to build a binary xxx from its WEB files is:
Move xxx.ch to the directory that contains xxx.web, apply tangle
to xxx.web and xxx.ch to generate xxx.p and xxx.pool, and compile the
Pascal source with fpc. The command line
   tgl xxx.web xxx.ch
will do all that. It produces xxx that you need to move to your binary
directory. Note tgl will not create xxx.pool, since this is only needed
by the ini-versions that are to be built by itgl.

METAFONT and TEX come in two versions: An initialization version
(initex, inimf) and a production version (tex, mf). To build the
initialization version, edit the change file to deactivate the change
blocks marked by "ini", and use itgl. To build the production version,
activate the change blocks marked by "ini" and use tgl.

A change block is active, if each of the web commands @x, @y and
@z are at the start of their lines, inactive if none of the web
commands are at the start of their lines and defect otherwise.
See webman.tex, section~11. for details on change files.

Step by step procedure to bootstrap TeX-FPC
-------------------------------------------
Install the Free Pascal Compiler
	https://freepascal.org/download.html 

Create the master directories (see above).

Copy the shell scripts from the tex-fpc/shell to your binary directory.


0. Compile tangle                                       tangle.p --> tangle
----------------------------------------------------------------------------
Compile tangle.p (fpc tangle.p) and move tangle to your
binary directory.

1. Make inimf and initex
------------------------
    mf.web,  mf.ch --> inimf, inimf.p, mf.pool
    ------------------------------------------

    tex.web, tex.ch --> initex,initex.p tex.pool
    --------------------------------------------

Make sure, the ini-change blocks in mf.ch and tex.ch are deactivated.
Build the ini-programs and save them as initex, resp. inimf.
Save tex.pool in  TeXformats and mf.pool in MFbases, use itgl instead
of tgl to keep inimf.p and initex.p and the .pool files.

2. Make plain.base                   lib/plain.mf --> MFbases/plain.base
------------------------------------------------------------------------
Go to the directory tex-fpc/mf and use inimf to create plain.base.
The file local.mf contains mode definitions for my HP LaserJet 1320
printer. Adapt local.mf to your printer and copy it to the mf directory.
	inimf ../lib/plain input local dump

Move plain.base to MFbases.

3. Make mf 					    mf.web, mf.ch --> mf
------------------------------------------------------------------------
Activate the the inimf-change block in mf.ch and build it with tgl.

4. Make gftopk                          gftopk.web, gftopk.ch --> gftopk
------------------------------------------------------------------------
Build gftopk in the mfware directory. You need gftopk to install
packed font files (.nnnpk) in the next step.

5. Install fonts:         MFinputs/*.mf --> TeXfonts/*.tfm, PKfonts/*.pk
------------------------------------------------------------------------
Prepare the stage directory to run both METAFONT (mk_MF_dir) and
TeX (mk_TeX_dir) and run the shell script MFT/plainfonts from there.
Check the file trouble that might contain commands that failed.

6. Make plain.fmt                 lib/plain.tex --> TeXformats/plain.fmt
------------------------------------------------------------------------
Copy lib/hyphen.tex to TeXinputs and go to the directory tex
to build plain.fmt.
This command line will do 
    initex ../lib/plain \\dump # one backslash is consumend by sh!
Move plain.fmt to TeXformats.

7. Finally build tex                             tex.web, tex.ch --> tex
------------------------------------------------------------------------
Activate the initex-change block in tex.ch and build it with tgl.

Happy weaving and happy type setting with your system!
Wolfgang Helbig,

Comments welcome: helbig@mailbox.org