summaryrefslogtreecommitdiff
path: root/dviware/dvi2bitmap/doc/doc.html
blob: 03c80f02150fb2147d9194839d30bcf1fe75ffd4 (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
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html xmlns:grddl="http://www.w3.org/2003/g/data-view#" grddl:transformation="http://ns.inria.fr/grddl/rdfa/2008/08/07/RDFa2RDFXML.xsl">
<head profile="http://www.w3.org/1999/xhtml/vocab">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link type="text/css" rel="stylesheet" href="style.css">
<title>dvi2bitmap – convert DVI files to bitmap images</title>
</head>

<body>
<h1 property="dc:title">dvi2bitmap – convert DVI files to bitmap images</h1>
<div class="abstract">
<meta property="dcterms:abstract" about="" content="This application processes a DVI file produced by TeX, converting each page to a single bitmap. The conversion is done directly, rather than through a chain of intermediate file formats, making the process extremely fast. It can produce output as XBM, XPM, GIF and PNG files.  ">
<p>This application processes a DVI file produced by
TeX, converting each page to a single bitmap.  The conversion is done
directly, rather than through a chain of intermediate file formats,
making the process extremely fast.  It can produce output as XBM, XPM,
GIF and PNG files.</p>
</div>

<div id="toc" class="toc"><ul>
<li><a href="#intro">1 Introduction</a></li>
<li><a href="#usage">2 Usage</a></li>
<li><a href="#usagenotes">3 Usage notes</a></li>
<li><a href="#libdvi2bitmap">4 The libdvi2bitmap library</a></li>
<li><a href="#install">5 Building and installing dvi2bitmap</a></li>
<li><a href="#developments">6 Bugs, extras, and further developments</a></li>
<li><a href="#refs">7 References and acknowledgements</a></li>
<li><a href="#sgml.maths">A Maths and SGML/HTML</a></li>
<li><a href="#tex.dimensions">B TeX dimensions</a></li>
<li><a href="#rn">C Release notes</a></li>
</ul></div>

<h2><a name="intro">1 Introduction</a></h2>


<p><kbd>dvi2bitmap</kbd> converts the typeset output of TeX into a bitmap image.</p>

<p>The most common use-case is to convert
TeX or LaTeX mathematics to HTML.  It is possible to do this with a chain of
general-purpose tools, for example going from DVI to postscript to PNM
files to GIFs, but this is generally slow.  For an overview of maths
and SGML/HTML, see <a href="#sgml.maths">A Maths and SGML/HTML</a>.</p>

<p>The tool dvi2bitmap does this processing in a single step,
reading the DVI file and font files, and emitting a bitmap.
It can, at present, generate XBM, XPM, GIF and, if the
relevant library is installed, PNG files.</p>

<p>See <a href="#usage">2 Usage</a> for usage instructions, and
<a href="#install.general"></a> for installation instructions.</p>

<p>The <code>dvi2bitmap</code> application is available for download at 
<span class="url">http://purl.org/nxg/dist/dvi2bitmap</span>.</p>

<p>This document matches version 1.0 of the program (you can
see what version you have with the command <kbd>dvi2bitmap
-V</kbd>).  This should currently be regarded as beta
software.</p>



<h2><a name="usage">2 Usage</a></h2>


<p>Synopsis:</p>
<pre>dvi2bitmap [flags] dvi-file</pre>
<p>This program is intended to conform to the DVI processing
standard.</p>

<p>The <code>dvi-file</code> argument is the name of a DVI file to be
converted to a bitmap.  dvi2bitmap looks for the file both with and
without the default extension <code>.dvi</code>.</p>

<p>You may also read the DVI file from the standard input by
giving the DVI file as <code>"-"</code>, thus</p>
<pre>cat myfile.dvi | dvi2bitmap -</pre>
<p>is an alternative way of reading the file (rather pointless in this
case, but it shows the principle; see <a href="#usagenotes.pipe">3.2 Using dvi2bitmap in a pipe</a>
for further discussion).
For more arcane purposes, the DVI file may also be specified as 
<code>&lt;osfile&gt;dvi-file</code>
(which is entirely equivalent), or 
<code>&lt;osfd&gt;integer</code>, where the given integer specifies an
open file descriptor; specifying <code>"-"</code> as the input file is
equivalent to <code>&lt;osfd&gt;0</code></p>

<p>The motivation for this program was the need for a helper program
to produce small bitmaps for inclusion in web pages.  Accordingly, the
program's underlying usage model is that one would generate a file of
TeX or LaTeX material, convert it to a DVI file using TeX, and
convert the result to a collection of bitmap files.  The input
text will typically be equations, but any other TeX material
will work as well.  For example, the processor which generates
the HTML could spit out a file such as</p>
<pre>\documentclass{article}
\pagestyle{empty}
\begin{document}
$E=mc^2$
\newpage
% etc...
\end{document}</pre>
<p>and then this program can scoot through it turning each page
into a bitmap.  I had thought about some complicated scheme to
delimit areas on the page, but realised that since the file
being processed would typically be generated on the fly
specifically for processing by a tool like this, this wasn't
really necessary.  See <a href="#developments">6 Bugs, extras, and further developments</a> for a script
which can help with this.</p>

<p>I hope that the program is (or can be made to be) flexible
enough to support other modes of use.</p>

<h3><a name="usage.options">2.1 Options</a></h3>


<p>Various of the options below have common syntax features.</p>
<dl>
<dt><code>[keyword-value-list]</code></dt>
<dd>
<p>This
indicates a sequence of <code>keyword=value</code> pairs,
separated by commas.  Not all keywords necessarily have a
value.</p>
</dd>

<dt><code>[boolean]</code></dt>
<dd><p>This can be `yes', `true' or `on' indicating
<em>true</em>; or `no', `false' or `off' indicating
<em>false</em>.</p></dd>
</dl>

<p>The options are as follows:</p>
<dl>
<dt><code>-c, --crop=[keyword-value-pairs]</code></dt>
<dd>
<p>The <code>--crop</code> option allows you to control
how the generated bitmaps are cropped before they are
written.  The keywords are `left', `right', `top',
`bottom' and `all', and the value in each case is the
number of pixels to leave as a margin.  If the keywords
`relative' (default) or `absolute' are present, they refer
to all of the keywords following: if the crop is specified
as `relative', then the values specify the number of
pixels to leave around the blackened pixels of the text;
if the crop is `absolute', then it specifies the position
of the crop (in pixels) from the left or top edge of the
`page'.  The specification
<code>----crop=absolute,all=dimen</code>, which would set
all the crops to the same position, is silly, and so is
forbidden.</p>

<p>The conversion from points to pixels takes account of
the magnification set in the
<code>--magnification</code> option, if that's been
specified already, but it doesn't notice if that's set
after this option, and it takes no account of any
magnification in the DVI file.</p>

<p>See <a href="#usage.special">2.2 DVI specials</a> for TeX
<code>\special</code> commands which set this within
the TeX file.</p>

<p>See below for TeX <code>\special</code> commands
which set this within the TeX file.</p>

</dd>

<dt><a name="usage.options.fp">
<code>-F, --font-search=[keyword-value-list]</code>
</a></dt>
<dd>
<p>Specifies how <code>dvi2bitmap</code> is to find
the fonts it needs.  Keywords are as follows:</p>

<p><code>path[=list]</code>: use the given list of
filesystem paths to search for PK fonts, or enable
using the default path, if <code>=path</code> is
missing.  The default path is given by the environment
variable <code>DVI2BITMAP_PK_PATH</code>.  See also
the discussion of font searching below.</p>

<p><code>kpathsea</code>: enable using the
<code>kpathsea</code> library to find fonts.  If the
program was not built against the
<code>kpathsea</code> library, this option has no
effect.</p>

<p><code>command[=script]</code>: enable using the given
script to find fonts.  If the argument is missing,
this enables using the script configured into the
program at compile-time.  This script is any program
which will search the filesystem and produce a single
line on output, giving the full path to the specified
font.  For example, this might be given as
<code>kpsewhich pk %f.%dpk</code> to run the
<code>kpsewhich</code> program.  The command name is a
font-string template, as described <a href="#usage.fonts.template">2.5.4 Font-string templates</a>.</p>

<p>If the program does not find a font using whichever
methods have been enabled then, following the pattern
of <code>dvips</code> and other DVIware, it writes a
file <code>missfont.log</code> in the current
directory, containing commands which you can use to
generate the fonts immediately or later.</p>

<p><code>none</code>: disable all font-searching.  The
result is that only the <code>missfont.log</code> file
is written.</p>

<p>Each of the keywords can be prefixed by `no' to turn
off the corresponding option -- thus
<code>--font-search=nopath,nokpathsea,nocommand</code>
has the same effect as
<code>--font-search=none</code>.</p>
</dd>

<dt>
<code>-G, --font-gen=[boolean], --font-gen=command[=script]</code>
</dt>
<dd>
<p>Switch automatic generation of fonts off and on.  If
<code>--font-gen=command</code> is given, then the
command specified at compile time is used to generate
fonts.  If, further, a font-generation script is
specified, then it will be used instead of the
default.  The specified script is a font-string
template, as described below.  The default for
automatic font generation is set at compile time.</p>
</dd>

<dt><a name="usage.options.g"><code>-g, --debug=[spec]</code></a></dt>
<dd>
<p>Switch on debugging.  The <code>[spec]</code> is a
list of letters indicating what to debug, as follows.
You may trace bitmap generation (`b'), DVI file parsing
(`d'), input (`i'), the main program (`m'), PK file
searching and parsing (`p'), font rasterdata parsing
(`r'), or various utility functions (`u', though this is
actually only useful for the maintainer).  If kpathsea
is compiled in, then debugging PK files switches on
kpathsea debugging also.  Adding an extra `g' at the
beginning of the spec increases
still further the amount of debugging code.  The
debugging information may be uninformative or
unintelligible; it might even crash the program (mention
that to me).</p>

</dd>

<dt><code>-h, --height=size; -w, --width=size</code></dt>
<dd>
<p>Specify the height and width of the canvas on which
the output bitmap is painted.  The program tries to
make an estimate of this based on information within
the DVI file, but it can't efficiently get all the
information it needs, so sometimes the estimate is
wrong.  If you get a warning message like
<code>Warning: p.12: bitmap too big: occupies
(1183,1072)...(4134,6255). Requested 4100x6200</code>
then you'll need to specify a bitmap size.  The
numbers <code>(1183,1072)...(4134,6255)</code> are the
coordinates of the top-left and bottom-right of the
bitmap: in this case <code>--height=6300
--width=4200</code> would suffice.  At some point, I'd
like to make the bitmap `expandable', obviating the
need for these options.</p>
</dd>

<dt><code>--help</code></dt>
<dd>
<p>Display outline help for the options on stderr, and
exit</p>
</dd>

<dt><code>-l, --end-page</code></dt>
<dd>
<p>See option <code>--start-page</code></p>
</dd>

<dt><a name="usage.options.fm"><code>-M,
--font-mode=[mode]</code></a></dt>
<dd>
<p>Set the MetaFont mode which is used for generating
font files.  The default is <code>ibmvga.</code> If
you set this, you will probably have to set the
resolution to a consistent number.</p>
</dd>

<dt><code>-m, --magnification=[number]</code></dt>
<dd>
<p>The TeX magnification parameter which is used when
processing the DVI file. It is a float, with 1.0
corresponding to no magnification (the default).  This
interacts with the resolution as follows: if you
specify a resolution of 100, and a magnification of 2,
then <code>dvi2bitmap</code> will search for PK files
at 200 dpi.</p>
</dd>

<dt><code>-n, --nodvi</code></dt>
<dd>
<p>Do not actually process the DVI file, but read the
DVI pre- and postamble.  Useful in conjunction with
the <code>--query</code> options.  If this option is
present, then the program returns non-zero if any
fonts were missing (see also <a href="#usage.exit">2.3 Exit value</a>).
The <code>-n</code> is for brevity and consistency
with other tools -- the behaviour can be alternatively
specified as <code>--process=nodvi</code></p>
</dd>

<dt><a name="usage.options.output"><code>-o,
--output=[filename-pattern]</code></a></dt>
<dd>
<p>Choose the output filename pattern.  The value is a
`printf' formatting string, with a single
<code>%d</code> formatting descriptor, which will be
replaced in output filenames with the page number.  If
there is no such descriptor, the filename `pattern' is
used as-is for the first filename output, after which
the program reverts to the default filename pattern.
The filename pattern can be overridden on a per-page
basis by a TeX <code>\special</code> embedded in the
DVI file (see <a href="#usage.special.opf"></a> in <a href="#usage.special">2.2 DVI specials</a>).  If there is no file extension,
or if it does not match the output type, a suitable
file extension will be added.</p>
</dd>

<dt><code>--pipe</code></dt>
<dd>
<p>Indicates that the dvi-file argument is a
non-seekable file, such as a named or unnamed pipe.
This is automatically the case if you specify the DVI
file as stdin, "-".</p>
</dd>

<dt>
<code>-p, --start-page=num</code>,
<code>-l, --end-page=num</code>,
<code>-P, --page-range=[spec]</code>
</dt>
<dd>
<p>These select page ranges, using a slight extension of
the notation used by <code>dvips</code> (and the same
option letters, except that <code>dvips</code> uses
<code>-pp</code> instead of <code>-P</code>).</p>

<p>The <code>--start-page=snum</code> and
<code>--end-page=enum</code> options take single page
numbers; if either of these is given, then the program
will process pages from page <code>snum</code> to page
<code>enum</code>, with the defaults being the
corresponding extremes.  The <code>[spec]</code>
consists of a comma-separated sequence of page numbers
and ranges (<code>a-b</code>); only those pages, and
the pages falling in those ranges (inclusive of the
end pages) are processed.  Any of these specifications
may be prefixed by either <code>=</code> or
<code>:n:</code>.  In the former case, DVI page
numbers are used rather than the TeX
<code>\count</code><img src="doc.img/m-175.gif"> register; in the latter
case, the program examines the
<code>\count</code><img src="doc.img/m-177.gif"> register rather than the
default <code>\count</code><img src="doc.img/m-179.gif"></p>

<p>You can specify both of these prefixes one or more
times, but you cannot mix the
<code>--start-page</code> and <code>--end-page</code>
options with the <code>--page-range</code> option.
The program will respect only the last
<code>--start-page</code> and <code>--end-page</code>
options, but the <code>--page-range</code> options are
cumulative.  There may be no spaces in the
<code>pagelist</code>.  The page numbers may be
negative.</p>

<p>Examples:</p>
<pre>dvi2bitmap --page-range=3,6-10 ...</pre>
<p>process only the specified pages</p>

<pre>dvi2bitmap --page-range=:2:1 ...</pre>
<p>process only pages where <code>\count2</code> was 1.</p>
</dd>

<dt><a name="usage.options.q"><code>-Q,
--query=[keyword-list]</code></a></dt>
<dd>
<p>Query various things.  The available possibilities
are as given below.  The results of each of the
queries is printed on a line by itself, prefixed by a
`Q', the keyword and a space, so that, for example,
each of the lines produced by the
<code>--query=missing-fonts</code> option would start
<code>Qmissing-fonts cmbx10 110 ...</code></p>

<p>Some of these options
(<code>--query=missing-fonts</code> and
<code>--query=missing-fontgen</code>) are probably
most useful with the <code>-n</code> or
<code>--process=options</code> options, to investigate
a DVI file before processing.  Others
(<code>--query=types</code> and
<code>--query=paper</code>) are probably useful only
with <code>--process=options</code>.  The option
<code>--query=bitmaps</code> is only useful if you do
actually generate bitmaps.  For consistency (and so
you don't have to remember which ones do which), the
appropriate <code>--process</code> option is
<em>not</em> implied in any of them, and you have to
give it explicitly.</p>

</dd>

<dt><code>--query=bitmaps</code></dt>
<dd>
<p>Prints on stdout a line for each bitmap it generates,
giving the filename, horizontal size, and vertical
size, in pixels.  This also reports the position of
any `mark' in the bitmap -- see <a href="#usage.special.mark"></a>.</p>
</dd>

<dt><code>-Qf, --query=missing-fonts</code></dt>
<dd>
<p>Show missing fonts.  The program writes on standard
output one line per missing font, starting with
<code>Qf</code> or <code>Qmissing-fonts</code>
(depending on which of the variants was given -- the
shorter ones are less mnemonic, but more convenient to
parse in scripts), then five fields: the font name,
the DPI value it was looking for, the base-DPI of the
font, the magnification factor, and a dummy metafont
mode.  This output might be massaged for use with the
mktexpk (TeXLive) or MakeTeXPK (teTeX) scripts to
generate the required fonts, but
<code>--query=missing-fontgen</code> is more
straightforward.</p>
</dd>

<dt><code>-QF, --query=all-fonts</code></dt>
<dd>
<p>As for <code>--query=missing-fonts</code> except that found
fonts are also listed, all prefixed by
<code>Qall-fonts</code></p>
</dd>

<dt><code>-Qg, --query=missing-fontgen</code></dt>
<dd>
<p>As for <code>--query=missing-fonts</code>, except
that the output consists of the string
<code>Qmissing-fontgen</code> followed by a
<code>mktexpk</code> or <code>MakeTeXPK</code> command
which can be used to generate the font.</p>
</dd>

<dt><code>-QG, --query=all-fontgen</code></dt>
<dd>
<p>As for <code>--query=missing-fonts</code>, except that
font-generation commands for found fonts are also listed, prefixed by
<code>Qall-fontgen.</code></p>

<p><em>Note</em>: Only one of
<code>--query=missing-fonts</code>,
<code>--query=all-fonts</code>,
<code>--query=missing-fontgen</code> and
<code>--query=all-fontgen</code> should be specified
-- if more than one appears, only the last one is
respected -- if more than one appears, only the last
one is respected.  In each of these four cases, plus
their short forms, font-generation is automatically
suppressed.  This is probably what you want (it's not
obvious why you're querying this otherwise), but if
you do not want this, then you can reenable font
generation with <code>--font-gen=true</code></p>
</dd>

<dt><code>--query=paper</code></dt>
<dd>
<p>Show the list of paper sizes which are predefined for the
<code>--paper-size</code> option.</p>
</dd>

<dt><code>--query=types</code></dt>
<dd>
<p>List the output image formats which the program can
generate, on stdout, separated by whitespace.  The
first output format is the default.</p>
</dd>

<dt><code>-r, --resolution=[number]</code></dt>
<dd>
<p>Specifies the output resolution, in pixels-per-inch.
This is used when deciding which PK files to use. The
default is 110, which matches the default
<code>ibmvga</code> metafont mode.</p>
</dd>

<dt><a name="usage.options.r"><code>-R,
--colours=[keyword-value-list],
--colors=[keyword-value-pairs]</code></a></dt>
<dd>
<p>Specifies the foreground or background colours, as
RGB triples.  The keywords are either
<code>foreground</code> or <code>background</code>,
and the values are a triple of integers separated by
slashes, for example
<code>--colours=foreground=127/127/255</code>.  The
integers must be in the range [0,255], and can be
specified in decimal, octal or hex (for example
<code>127=0177=0x7f</code>), or else the whole spec
may be of the form <code>#rrggbb</code>, where `rr',
`gg' and `bb' are each a pair of hex digits.</p>
</dd>

<dt><code>-s, --scaledown=[number]</code></dt>
<dd>
<p>Reduces the linear size of the output bitmap by the
given factor (default 1).</p>
</dd>

<dt><code>-T, --output=type=[type]</code></dt>
<dd>
<p>Choose the output format, which can be
<code>png</code>, <code>gif</code>, <code>xpm</code>
or <code>xbm</code>.  The program generates XBM
bitmaps by default, and has simple support for XPM.
The GIF and PNG options may not be available if they
weren't selected when the program was configured.</p>
</dd>

<dt><code>-t, --paper-size=papersize</code></dt>
<dd>
<p>Set the initial size of the bitmap to be one of the
paper sizes returned by <code>--query=paper</code>.
This is useful either to make sure that there is
enough room on the initial bitmap, to avoid the
warning above, or, along with the
<code>--process=nocrop</code> option, to force the
output bitmap to be a certain size.</p>
</dd>

<dt><code>-v, --verbose=[quiet|silent]</code></dt>
<dd>
<p>Quiet mode suppresses some chatter, and silent mode suppresses
chatter, and does not display warnings or errors
either.</p>
</dd>

<dt><code>-V, --version</code></dt>
<dd>
<p>Display the version number and compilation options,
and exit.</p>
</dd>

<dt><code>-X, --process=[keyword-value-list]</code></dt>
<dd>
<p>Specifies the processing to be done.  Keywords are as
follows:</p>

<p><code>dvi</code> and <code>nodvi</code> : enable or
disable processing of the DVI file.  If disabled, we
do not require a DVI file to be present on the command
line.  The <code>nodvi</code> option is useful with
some of the <code>--query</code> options.</p>

<p><code>postamble</code> and <code>nopostamble</code>:
enable or disable processing of the DVI postamble.  If
dvi2bitmap is called to invoke a non-seekable device
such as a pipe, you should disable processing of the
postamble.  Disabling the postamble processing is
incompatible with the <code>--query</code> options
which examine the fonts in the file.  By default, both
the DVI body and the postamble are processed.</p>

<p><code>--process=options</code>: shorthand for
<code>--process=nopreamble,nodvi,nopostamble</code>.
Only the options are examined.</p>

<p><code>blur</code> and <code>noblur</code>: if true,
blurs the bitmap, making a half-hearted attempt to
make a low-resolution bitmap look better.  This really
isn't up to much -- if you have the fonts available,
or are prepared to wait for them to be generated, a
better way is to use the <code>--magnification</code>
option to magnify the DVI file, and then the
<code>--scale</code> option to scale it back down to
the correct size.</p>

<p><code>transparent</code> and
<code>notransparent</code>: if true, this makes the
output bitmap have a transparent background, if that's
supported by the particular format you choose using
option <code>--output-type</code></p>

<p><code>crop</code> and <code>nocrop</code>: if true,
specifies that you want the output bitmap to be
cropped.  This is true by default, so you'll most
often use the <code>crop=false</code> to specify that
you do not want the output cropped (for example, if
you're using the <code>--paper-size</code> option and
want the output to stay the specified size).</p>

<p>By default, bitmaps are not blurred, are cropped, and
are transparent if possible.</p>

<p>For PNG files, the output bitmap uses a palette plus
an alpha channel; these are calculated in such a way
that if you display the resulting bitmap on the same
colour background as <code>dvi2bitmap</code> was using
(which is white by default, but can be specified using
the <a href="#usage.special.fg"></a>) then the result should look identical
to the result with no transparency information, but
probably progressively worse the further the
background moves from this.  I suppose, but can't at
present check, that this implies that you should
choose a mid-grey background colour when making such
transparent PNGs.  I'd welcome advice on this
point.</p>
</dd>
</dl>


<h3><a name="usage.special">2.2 DVI specials</a></h3>


<p>dvi2bitmap recognises several DVI special commands, and emits a
warning if it finds any others.</p>

<p>The syntax of the special commands is</p>
<pre>\special{dvi2bitmap &lt;special-command&gt;+ }</pre>
<p>There may be one or more <code>&lt;special-command&gt;</code>
sequences within a single special.</p>

<p>The <code>&lt;special-command&gt;</code> which the program
recognises are:</p>
<dl>
<dt><code>default</code></dt>
<dd><p>Makes other special-commands in this same special affect
defaults.  See those commands for details.</p></dd>

<dt><a name="usage.special.opf"><code>outputfile &lt;filename&gt;</code></a></dt>
<dd>
<p>The output file used for the current page will be
named <code>filename.gif</code> (if the output type
were `gif').  A filename extension will be added if
none is present, or if it does not match the output
type selected.</p>

<p>If the <code>default</code> command has been given,
then this instead specifies the default filename
pattern, and the `filename' should contain a single
instance of either <code>%d</code> or <code>#</code>;
if there is no such instance, one will be implicitly
added at the end.</p>

<p>The <code>%d</code> is precisely analogous to the
behaviour of the <a href="#usage.options.output"></a> option.
However it is actually rather tricky to get an
unadorned percent character into a TeX special, unless
you play catcode tricks, and this is why you may
alternatively include a <code>#</code> character to
indicate where the page number should go.  In fact,
since it is <em>also</em> rather tricky to get a
single <code>#</code> character in a special, any
immediately following <code>#</code> characters are
ignored.  Thus the recommended way of specifying this
special is through something of the form</p>
<pre>
\special{dvi2bitmap default outputfile myfile-#}
</pre>
<p>using the <code>#</code> form,
and letting the file extension be controlled by the
output type which is actually used.</p>
</dd>

<dt><code>absolute</code></dt>
<dd>
<p>Affects the <code>crop</code> command.</p>
</dd>

<dt><code>crop &lt;side&gt; &lt;dimen&gt;</code></dt>
<dd>
<p>Crop the bitmap on the current page so that the
specified edge of the bitmap is
<code>&lt;dimen&gt;</code> points away from the
bounding box of the blackened pixels.
<code>&lt;side&gt;</code> may be one of `left',
`right', `top', `bottom' or `all', referring to the
corresponding edge, or all four edges at once.  If the
<code>default</code> command has been given in this
special, then this pattern of cropping is additionally
made the default for subsequent pages.  If the
<code>absolute</code> command has been given, then the
crop position is set at <code>&lt;dimen&gt;</code>
points from the appropriate edge of the `paper'.</p>

<p>The <code>-c</code> and <code>-C</code> command-line
options (<a href="#usage.options">2.1 Options</a>) have the effect of
setting initial defaults.  In the absence of either of
these, the initial crop is exactly at the bounding
box.</p>
</dd>

<dt><code>default imageformat &lt;format&gt;</code></dt>
<dd>
<p>Set the default image format, which should be one of
the keywords `xbm', `xpm' `gif', `png'.  This is
equivalent to specifying the image format through the
<code>-t</code> option (section <a href="#usage.options">2.1 Options</a>).</p>

<p>The keyword is just <code>imageformat</code>, but you
must specify the <code>default</code> keyword when you
specify <code>imageformat</code>; this is for
consistency, and makes it clear that this is setting a
default format rather than setting the format only for
the next image (that's not implemented at present, but
could be added).</p>
</dd>

<dt><a name="usage.special.fg"><code>default foreground|background
&lt;red&gt; &lt;green&gt; &lt;blue&gt;</code> </a></dt>
<dd>
<p>Sets the (default) foreground and background colours
for text.  This works, as long as you specify the
colour change before any text is output, since you
can't, at present, change the colours after that.
Specifically, you can't change the colours for a
fragment of text in the middle of a page; for this
reason, and as with <code>imageformat</code> you
should at present always include the
<code>default</code> keyword when using this
special.  The integers must be in the range
[0,255], and can be specified in decimal, octal or
hex (ie, <code>127=0177=0x7f</code>).</p>
</dd>

<dt><code>strut &lt;left&gt; &lt;right&gt; &lt;top&gt;
&lt;bottom&gt;</code></dt>
<dd>
<p>This places a `strut' in the
generated file.  Using the usual TeX
<code>\strut</code> won't work: that would leave the
appropriate space when TeXing the file, but that space
doesn't explicitly appear in the DVI file (which is
just a bunch of characters and locations), so when
<code>dvi2bitmap</code> fits its tight bounding box to
the blackened pixels in the file, it knows nothing of
the extra space you want.</p>

<p>The `strut' special forces the bounding box to be at
least `left', `right', `top' and `bottom' points away
from the position in the file where this special
appears.  All the dimensions must be positive, and
they are floats rather than integers.</p>

<p>If you wanted to set a page containing only the maths
`<code>${}^\circ$</code>' (why, is another matter),
<code>dvi2bitmap</code> would normally make a tight
bounding box for the bitmap, so that you'd get an
image containing only the circle (unless other crop
options were in force).  If, in this case, you put in
a special such as <code>\special{dvi2bitmap strut 0 2
10 2.5}</code>, you would force the bounding box to
come no closer than 0pt to the left of the position in
the file where this special appears, 2pt to the right,
10pt above and 2.5pt below.</p>

<p>A useful bit of TeX magic is:</p>
<pre>{\catcode`p=12 \catcode`t=12 \gdef\DB@PT#1pt{#1}}
\def\DBstrut{\strut\special{dvi2bitmap strut 0 0 
\expandafter\DB@PT\the\ht\strutbox\space\expandafter\DB@PT\the\dp\strutbox}}
</pre>
<p>Once you've done that, the command
<code>\DBstrut</code> will put an appropriate strut in
the output.</p>
</dd>

<dt><a name="usage.special.mark"><code>mark</code></a></dt>
<dd>
<p>This sets a `mark' in the generated file, which is
reported when you specify <code>--query=bitmaps</code>
(see <a href="#usage.options.q"></a>).  Normally,
<code>--query=bitmaps</code> writes out the horizontal
and vertical size of the generated bitmap.  If use of
this special has placed a `mark' in the bitmap,
however, then the <code>--query</code> option also
reports the position of that mark, as a position
within the bitmap, such that the top-left corner of
the bitmap has coordinates <img src="doc.img/m-429.gif">.  For
example, after</p>
<pre>
\noindent\special{dvi2bitmap mark}Hello
</pre>
<p>the command line</p>
<pre>dvi2bitmap --query=bitmaps foo
</pre>
<p>might report</p>
<pre>
Qbitmaps foo-page1.png 80 14 -1 10
</pre>
<p>indicating that the bitmap is 80 pixels
wide by 14 high, and that the reference point, after
cropping, is at position <img src="doc.img/m-436.gif">.  The `-1'
is because the mark appears to the left of the `H' of
`Hello' (and the `H' probably has some negative
offset), and the `10' indicates that the baseline of
this text is 10 pixels from the top of the bitmap;
this latter information might be useful when working
out how to position this bitmap within a generated
HTML file.  See <a href="#usagenotes.marks">3.4 Using marks to position bitmaps</a> for a
discussion of how to do that.</p>

<p>Both here and in the support for the `strut' special,
there is a great deal of scope for off-by-one errors;
also it's unclear what is the best interface to this
functionality, so it's possible that this might change
in subsequent versions.  The author welcomes
comments.</p>
</dd>

<dt><a name="usage.special.unit"><code>unit
&lt;u&gt;</code></a></dt>
<dd>
<p>The units in the `strut' and `crop' specials are by
default in TeX points.  You may switch to a different
unit with the `unit' special.  The specifier `u' gives
a unit name, which may be selected from the set of
units TeX knows about (`pt', `bp', `cm', and so on),
plus `pixels', and `dvi' to select DVI file units
(usually the same as `sp').  If the `default'
qualifier is present, this setting applies to
subsequent special strings as well.</p>
</dd>

</dl>

<p>For example, the pair of commands</p>
<pre>\special{dvi2bitmap default outputfile trial-# unit pc crop all 5}
\special{dvi2bitmap absolute crop left 5}
</pre>
<p>will change the output filename pattern for the rest of the DVI file,
and set a 5pc margin round the bounding box.  The current page,
however, will have a left-hand crop five points in from the left hand
side.  Remember that TeX's origin is one inch from the left and the
top of the paper, and it is with respect to this origin that the
program reckons the absolute distances for the cropping.</p>



<h3><a name="usage.exit">2.3 Exit value</a></h3>


<p>Exits with a non-zero status if there were any processing errors.
Having <em>no</em> fonts present counts as a processing error.</p>

<p>If there is at least one font present, then missing fonts
will be replaced by the first <code>cmr10</code> font it
finds, or a more-or-less randomly chosen alternative if that
font is not used at all.  The program will produce a warning
if the <code>-q</code> option is not present, but it will
return with a zero (success) status.</p>

<p>Exception: If the <code>-n</code> option (see <a href="#usage.options">2.1 Options</a>) is present, then the program returns
success only if <em>all</em> fonts are present. </p>



<h3><a name="usage.examples">2.4 Examples</a></h3>


<p>Basic usage examples.</p>

<pre>
% dvi2bitmap --resolution=110 --magnification=2 --scale=2 \
--output-type=gif hello.dvi
</pre>
<p>This converts the file <code>hello.dvi</code> to a GIF
bitmap.  It first sets the magnification factor to 2, so
that the program uses a double-size font (eg,
<code>.../cmr10.220pk</code>), then scales the bitmap down
by a factor of 2 to obtain a bitmap of the correct size.</p>

<pre>
% dvi2bitmap -n -Qf --resolution=110 --magnification=1.5 \
--verbose=quiet hello.dvi
Qf cmr10 165 110 1.5 localfont
</pre>
<p>This reads the DVI file to find out what fonts are required, but does
not process it further.  It then tries to find the fonts, fails, and
produces a list of parameters which could be used to generate the
font files.  </p>

<p>See also <a href="#usage.fonts">2.5 Finding and generating fonts</a>, and see <a href="#usagenotes">3 Usage notes</a> for more elaborate examples of use.</p>



<h3><a name="usage.fonts">2.5 Finding and generating fonts</a></h3>


<h4><a name="usage.fonts.finding">2.5.1 Finding fonts</a></h4>


<p>The program searches for fonts using a number of mechanisms.</p>

<ol>
<li>
<p>The <code>-fp</code> option (see <span><a href="#usage.options.fp"></a></span><span>above</span>) specifies a
colon-separated list of filename templates which
should be searched for font PK files.  If this is
given on the command line, it overrides...</p>
</li>

<li>
<p>The <code>DVI2BITMAP_PK_PATH</code> environment
variable, if defined, specifies a colon-separated
list of filename templates which are to be searched
for PK files.</p>
</li>

<li>
<p>If the program cannot find fonts using the
environment variable, and if it was configured with
support for the <code>kpathsea</code> library (see
<a href="#install.general"></a>), then it should
find PK files using the same mechanism other DVI
processors use.  </p>
</li>

<li><p><code>dvi2bitmap</code> can be configured to use
a script to find fonts.  If the program was not
configured to use <code>kpathsea</code> or the
search fails, then the program invokes a script
which knows where to find font files, given a search
pattern, and which returns a single line containing
a discovered font filename.  See <a href="#conf.with-fontfinder"></a>.  </p></li>
</ol>

<p>The third method is the ideal -- you should build
<code>dvi2bitmap</code> using the <code>kpathsea</code>
library if possible (see <a href="#install.web2c">5.1 Obtaining the kpathsea library</a> for how
to obtain it): it is because other DVI-processing programs
like <code>dvips</code> and <code>xdvi</code> are built
with the <code>kpathsea</code> library, that you normally
never have to worry about where fonts live.  The
<code>kpathsea</code> library is generally integrated with
the font-generation commands, and can be queried using the
<code>kpsewhich</code> command.</p>

<p>There are one or two possible wrinkles with the third
method.  The path-searching library is very powerful and
flexible, but it is possible to be tripped up by its
configuration file.</p>

<p>Firstly, the program has to <em>find</em> the
configuration file.  The program should sort this out for
itself at configuration time, but it is possible that you
might have to give it some help.  If you specify the
<code>TEXMFCNF</code> environment variable, setting it to
the directory which contains your TeX installation's
<code>texmf.cnf</code> file, then this overrides the
program's notion of where the configuration should be.
You can find this file using the command <kbd>kpsewhich
cnf texmf.cnf</kbd>.</p>

<p>Secondly, it's possible to break the configuration file.
Certain TeX distributions (the ones that came with early RedHat 6.x
distributions are ones I know about) are broken in an
unfortunate way. See <a href="#usage.fonts.notfinding">2.5.2 Not finding fonts</a>
for a discussion.</p>


<h4><a name="usage.fonts.notfinding">2.5.2 Not finding fonts</a></h4>


<p>It can sometimes happen that <code>dvi2bitmap</code> fails to find fonts,
successfully calls <code>mktexpk</code> to build them, but then <em>still</em>
fails to find them, even though <code>mktexpk</code> has put them where they
should be.  There are (at least) three possible reasons for this.</p>

<p>If you are using the <code>kpathsea</code> library, there
might be some misconfiguration which is confusing it.  You
can trace <code>kpathsea</code>'s deliberations in massive
detail by giving the option <code>-ggp</code> (<a href="#usage.options.g"></a>).</p>

<p>Perhaps you do not have the <code>kpathsea</code> library
installed, or have disabled it, but you <em>have</em>
requested that font-generation be enabled (see <a href="#install.general"></a>).  What happens in this case is
that <code>mktexpk</code> successfully builds the fonts,
and installs them in the correct place, where `correct
place' means `the place where <code>kpathsea</code> would
find them'; you're not using <code>kpathsea</code>, so no
fonts for you.  What you have to do in this case is work
out where the `correct place' is (<code>kpsepath</code>
and <code>kpsewhich</code> can help here), and specify
that place using either the <code>-fp</code> option or the
<code>DVI2BITMAP_PK_PATH</code> variable, as above (this
is confusing, I know, but more-or-less unavoidable, since
we are here trying to do <code>kpathsea</code>'s job,
without <code>kpathsea</code>).</p>

<p>I think it is also possible to fall victim to a race
condition, where the font is built successfully, but the
program looks for it in the correct place before the font
is fully flushed to disk, or (mumble) something like that.
Simply running <code>dvi2bitmap</code> a second time seems
to work OK.  I'm not sure precisely what's going on here,
and I'd welcome more precise observations, here.</p>

<p>Another, slightly nastier reason is as follows.</p>

<p>Some <code>texmf.cnf</code> files declare the location of
the user-writable font directory though a setting like</p>
<pre>VARTEXFONTS=$SELFAUTOPARENT/var/lib/texmf</pre>
<p>whereas others have something like</p>
<pre>VARTEXFONTS=$TEXMFLOCAL/fonts</pre>
<p>Now,
<code>$SELFAUTOPARENT</code> is a variable which is set by
the kpathsea library to be the grandparent directory of
the executable which uses the library.  So, for
<code>/usr/bin/{tex,latex,mktexpk,...}</code>, it's
<code>/</code>, but if your <code>dvi2bitmap</code> binary
doesn't live with the other dvi-ware then its
<code>$SELFAUTOPARENT</code> will be different, so that
<code>dvi2bitmap</code> will look for fonts in a
<em>different</em> place from the place where
<code>mktexpk</code> put them when it successfully
generated them.</p>

<p>I would argue fairly strongly that having the
<code>VARTEXFONTS</code> directory depend on the location
of the dvi-ware <em>executables</em> is a very silly thing
to do.  This was the case in the teTeX distribution which
came with RedHat 6.0, though this was fixed pretty
rapidly.  If you've fallen foul of this, then you can
either</p>
<ul>
<li>
<p>change your <code>texmf.cnf</code> file to
something more like the second example above; or</p>
</li>

<li><p>install <code>dvi2bitmap</code> along with the
other TeXware.</p></li>
</ul>
<p>I'd much prefer the first alternative, myself.</p>

<p>A third option is to get <code>dvi2bitmap</code> to work
around the problem, by telling it to claim to be some
program which <em>is</em> installed along with the other
dvi-ware.  You do this with the
<code>--enable-fake-progname</code> option to the
configuration script (see <a href="#conf.enable-fake-progname"></a>).</p>


<h4><a name="idm341584259600">2.5.3 Generating fonts by hand</a></h4>


<p>If you didn't enable automatic font-generation, or if you
did and something went wrong, you might have to generate
fonts by hand.  You need to look at the documentation for
your TeX system, specifically the <code>mktexpk</code> and
<code>MakeTeXPK</code> scripts (one of which might be just
an interface to the other).</p>

<p>See the discussion of the `<code>make test</code>' script
in <a href="#usage.fonts.finding">2.5.1 Finding fonts</a>.  Also, note that the
option <code>-Qg</code>, given to <code>dvi2bitmap</code>,
displays the font-generation commands which would be
required to build the fonts missing from the specified DVI
file.  These are the commands which
<code>dvi2bitmap</code> would employ to generate these
fonts, when automatic-font-generation is enabled.</p>

<p>Since dvi2bitmap's default resolution is 72 dpi, as
opposed to the usual printer resolution of 300 or 600 dpi,
you are unlikely to have suitable fonts on your system,
and will need to generate them.  The program will generate
these automatically, if it was configured with support for
that (see <a href="#install.general"></a>); if it wasn't
configured with that support, or if the automatic font
generation fails, you might need to generate the fonts by
hand.</p>

<p>How you generate fonts depends on your TeX distribution.
As explained in <a href="#usage.examples">2.4 Examples</a>, you can
determine which fonts you need using the <code>-Qf</code>
option.  The teTeX and TeXLive TeX distributions include
scripts to generate fonts for you; if you have a different
distribution, there might be a similar script for you to
use, or you might have to do it by hand.  In the case of
teTeX, the command you'd use in the example above would
be:</p>
<pre>
% MakeTeXPK cmr10 165 110 1.5 ibmvga</pre>
<p>
This would generate fonts using the
<code>ibmvga</code> Metafont mode, using a base resolution
of 110 dpi (the default for that mode), at a magnification
of 1.5 times, giving a resultant resolution of 165 dpi.</p>

<p>If you're using the TeXLive distribution, the equivalent
command would be:</p>
<pre>
% mktexpk --mfmode ibmvga --mag 1.5 --bdpi 110 --dpi 165 cmr10</pre>

<p>If you want to use the same mode as you use for printing
documents, then the mode <code>localfont</code> should do
the right thing.  Otherwise, and probably better if these
images are intended for the screen rather than paper, you
could use a more specialised mode such as
<code>ibmvga</code>, which has been tweaked to be readable
at small resolutions.  See the file <code>modes.mf</code>
somewhere in your metafont distribution for the list of
possibilities.</p>

<p>After you have created the fonts, try giving the command</p>
<pre>
% kpsewhich pk cmr10.165pk</pre>
<p>
to confirm
that TeX and friends can find the new fonts, and that your
dvi2bitmap environment variable is set correctly.  This
command is part of the <code>kpathsea</code> distribution,
rather than the core TeX distribution, so may not be
present on your system.</p>


<h4><a name="usage.fonts.template">2.5.4 Font-string templates</a></h4>


<p>The search-path and font-finder routes use font-string
templates.  Here, the components of a font file name, or a
font-finding command, are specified using placeholders like
<code>%f</code>.  You may use</p>
<table>
<tr>
<td><code>%M</code></td>
<td>mode (eg. ibmvga)</td>
</tr>
<tr>
<td><code>%f</code></td>
<td>font name (eg. cmr10)</td>
</tr>
<tr>
<td><code>%d</code></td>
<td>dpi (eg. 330)</td>
</tr>
<tr>
<td><code>%b</code></td>
<td>base dpi (eg. 110)</td>
</tr>
<tr>
<td><code>%m</code></td>
<td>magnification (eg. 3)</td>
</tr>
<tr>
<td><code>%%</code></td>
<td>%</td>
</tr>
</table>
<p>Thus, using these values as an example, if one of the
entries in <code>DVI2BITMAP_PK_PATH</code> were <code>/var/tmp/%M/%f.%dpk</code>, this would
expand into <code>/var/tmp/ibmvga/cmr10.330pk</code>.
Alternatively, if we had given the font-finder script as
<code>/usr/local/teTeX/bin/kpsewhich pk %f.%dpk</code>,
the <code>dvi2bitmap</code> would have executed the
command <code>.../kpsewhich pk cmr10.330pk</code>, which
would have returned with a suitable font path.</p>





<h2><a name="usagenotes">3 Usage notes</a></h2>


<h3><a name="usagenotes.fonts">3.1 Good choices of fonts and scaling</a></h3>


<p>There is a certain amount of subtlety in choosing fonts and
resolutions for maximum readability.</p>

<p>The fonts that <code>dvi2bitmap</code> (currently) uses by
default are from the <code>cmr</code> family, and generated
using Metafont mode <code>ibmvga</code>, chosen because its
design resolution, of 110 pixels to the inch, is
approximately right for bitmaps viewed on the screen.  This
is not, however, necessarily the optimal choice in all
circumstances.</p>

<p>You can produce some simple antialiasing by magnifying the
output bitmaps then scaling them down, so that:</p>
<pre>
% dvi2bitmap --magnification=2 --scale=2 myfile.dvi</pre>
<p>
doubles the size of the bitmaps, then halfs it, effectively
blurring it in the latter stage.  This works quite well.
You don't <em>necessarily</em> get better results with
larger factors (though it does, of course, depend on the
situation), because Metafont already does some work to make
the characters easier to read, and I suspect that excessive
antialiasing merely frustrates this.</p>

<p>If you choose a different Metafont mode, it can make a
difference.  In your TeX distribution, there should be a
file called <code>modes.mf</code>, containing a large
collection of Metafont font-generation modes (look for it
using <code>kpsewhich modes.mf</code> if you have that
command), and there are several modes in this set which have
resolutions in the 70 to 200 range, which are therefore
about the right size to be useful in this context.  You're
probably aiming for a resolution of around 100 pixels per
inch, if you want the text in the output bitmap to be around
the same size as the other text on your monitor.  For
example, try the <code>ncd</code> and <code>nec</code>
modes:</p>
<pre>
% dvi2bitmap --magnification=2 --scale=2 --font-mode=ncd --resolution=95 try.dvi 
% dvi2bitmap --scale=2 --font-mode=nec --resolution=180 try.dvi 
% dvi2bitmap --magnification=2 --scale=4 --font-mode=nec --resolution=180 try.dvi</pre>
<p>
Note that the declared
resolution must match the font mode -- the default
resolution of 110 is designed to match the default mode of
<code>ibmvga</code>.  Also the <code>nec</code> mode,
because its base resolution is large anyway, only needs to
be scaled down to get adequate antialiasing.</p>

<p>It should be possible to create a Metafont mode
specifically for <code>dvi2bitmap</code> applications.  That
might be a useful project for someone!</p>

<p>Another thing to look at is whether changing the font
family can help.  The Computer Modern family is, of course,
designed for paper.  The <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=concrete">Concrete
Math family</a>, though also designed primarily for
paper, has features which make it particularly suitable for
this application.  The <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=psfchoice">FAQ
article which discusses maths font choices</a> remarks
that</p>
<blockquote><p>Since Concrete is considerably darker
than Computer Modern, this variant may be of particular
interest for use in low-resolution printing or in
display-oriented applications such as posters,
transparencies, or online documents.</p></blockquote>
<p>As
well as this, these fonts have rather simpler outlines than
Computer Modern <em>and</em> they are rather more upright,
both of which make them more robust to being rendered at
rather small resolutions.</p>

<p>You can use the concrete maths fonts simply by adding the
declaration</p>
<pre>
\usepackage{concmath}</pre>
<p>
to the preamble of your LaTeX document.  In tests, the best
configuration for clarity in a bitmap appeared to be a
document using the concrete maths fonts, plus the
<code>dvi2bitmap</code> invocation</p>
<pre>
% dvi2bitmap --magnification=2 --scale=4 --font-mode=nec --resolution=180 try-cc.dvi</pre>

<p>Any observations on this topic would be warmly
appreciated.</p>

<p>Many thanks to Doug du Boulay at <code>titech.ac.jp</code>
for raising this issue, for thus prompting me to discuss the
various options, and for then doing the critical testing
work.</p>



<h3><a name="usagenotes.pipe">3.2 Using dvi2bitmap in a pipe</a></h3>


<p><code>dvi2bitmap</code> is perfectly happy reading DVI
files from a pipe, so that</p>
<pre>
cat myfile.dvi | dvi2bitmap --pipe -</pre>
<p>
will work perfectly well.
Since the program knows that the standard input -- indicated
by the <code>-</code> argument to <code>dvi2bitmap</code> --
is not seekable, the option <code>--pipe</code> is actually
redundant.  This is not by itself particularly useful, since
TeX is not written to send its DVI output into a pipe.</p>

<p>If, however, you make a `named pipe' beforehand, using the Unix
<code>mkfifo</code> command (a FIFO, or first-in-first-out, is the
other name for such an object), then TeX can be persuaded to send its
output there.</p>
<pre>
% mkfifo myfile.dvi
% ls -l myfile.dvi
prw-r--r--  1 norman  admin  0 Aug 12 00:18 myfile.dvi
% latex myfile &gt;myfile.stdout &amp;
% dvi2bitmap --pipe mkfile.dvi</pre>
<p>
Here, we create the FIFO using the <code>mkfifo</code>
command; looking at it, we see that the first character on
the <code>ls</code> line is a <code>p</code>, indicating the
type of object it is.  We start (La)TeX going in the
background (achieved by the <code>&amp;</code>), putting its
chatty output into a file, and it merrily writes into the
`file' <code>myfile.dvi</code>.  Immediately afterwards
(we've shown this on two lines, but the two commands could
be run together with only the <code>&amp;</code> separating
them) we start <code>dvi2bitmap</code>, telling it to read
from the named pipe.  The pipe effectively synchronises the
two processes, so that if there is nothing to read,
<code>dvi2bitmap</code> is briefly suspended, and if the
pipe is full, LaTeX is suspended.  After this performance,
the DVI file, <code>myfile.dvi</code> ends up zero size
again, and the process can be repeated.</p>

<p>You can go further than this, and use a FIFO for LaTeX's input,
too:</p>
<pre>
% mkfifo myfile.tex myfile.dvi
% cat foo.tex &gt;myfile.tex &amp; \
latex '\input myfile.tex' &gt;myfile.stderr &amp; \
dvi2bitmap --pipe myfile.dvi</pre>
<p>
(the trailing backslashes indicate that this second set of
commands is all on one line).  The rather odd form of LaTeX
invocation (note the quotes) stops TeX from peeking at the
file, looking for the magic <code>%&amp;</code> line which
can tell it which format to use; since the input is a pipe,
it's unseekable, so we must use this form, or else LaTeX
fails.</p>



<h3><a name="usagenotes.multieqs">3.3 Processing many bitmaps</a></h3>


<p>If you have a large number of fragments of TeX to process,
it is best not to invoke <code>dvi2bitmap</code> for each one
individually.  Also, the program does not (yet) allow you to specify
more than one DVI file as input.  In this situation, it is best to
generate an input TeX or LaTeX file which contains <em>all</em> of the
text you wish to process, with one fragment per page.</p>

<p>For example, the following can help:</p>
<pre>
\documentclass{article}
\pagestyle{empty}
\special{dvi2bitmap default imageformat png}
\newcommand{\neweq}[1]{\vfil\break\special{dvi2bitmap outputfile #1.png}}
\begin{document}

\neweq{index-html-alpha}
$\alpha$

\neweq{index-html-aprime}
$A'=(0,\alpha,0,0)$

[...]

\end{document}</pre>
<p>
That includes a special to make PNG the default output format, and
defines a command sequence, <code>\neweq</code> which simultaneously
forces a new page and inserts a special to name the output file.  A
script which generates a file like this and then looks for the
resulting bitmaps, with known names of course, can run very
efficiently.  Combining that with the techniques in <a href="#usagenotes.pipe">3.2 Using dvi2bitmap in a pipe</a> can work wonders.</p>



<h3><a name="usagenotes.marks">3.4 Using marks to position bitmaps</a></h3>


<p>When including small images in an HTML page, it can be
difficult to get the images to line up with the rest of the
text, because a text with descenders (characters which go
below the line such as `p' or `g') cause the image to be
offset from the text line.  You can use the `mark' facility
to tell you how much you need to offset such an image so
that it lines up properly with the surrounding text.</p>

<p>For example, consider the following usage:</p>
<pre>
% cat temp.tex
\nopagenumbers
\noindent\special{dvi2bitmap mark}%
Hello, this is dvi2bitmap
\bye
% tex temp.tex
This is TeX, Version 3.14159 (Web2C 7.3.11)
(./temp.tex [1] )
Output written on temp.dvi (1 page, 240 bytes).
Transcript written on temp.log.</pre>
<p>
So, a simple test file with a single line in it, with descenders (the
`p').  The `mark' special goes at the beginning, following \noindent.
This is important, otherwise the point that is marked is the very
top-left of the image, not the bottom-left.</p>

<p>The output with <code>--query=bitmaps</code> is:</p>
<pre>
% dvi2bitmap --verbose=quiet --query=bitmaps temp
Qbitmaps temp-page1.png 163 14 -1 11</pre>
<p>
...where <code>verbose=quiet</code> has been used to turn
off the usual chatter.  It tells us that the bitmap as a
whole is 14 pixels deep, and that the mark, which is on the
TeX baseline, remember, is at position (-1,11) relative to
an origin at the top-left of the bitmap; or in other words
there's 3 pixels of space between the TeX baseline and the
bottom of the image.  We therefore know that we need to
offset the image by three pixels to make it line up
properly.</p>

<p>There are several ways to do that, but one way is to use
per-element CSS properties, like this:</p>
<pre>
% dvi2bitmap --verbose=quiet --query=bitmaps temp | awk  
'{printf "&lt;img src=\"%s\" style=\"margin-bottom: %dpx\"/&gt;\n", $2,  
$6-$4}'
&lt;img src="temp-page1.png" style="margin-bottom: -3px"/&gt;
%</pre>
<p>
So that's generated an <code>&lt;img&gt;</code> element
which has the correct `src' attribute (from column 2 of the
Qbitmaps line) and the correct offset (column6 - column4).
That uses awk, but if you're generating your HTML pages with
something like Perl or Python (substantially more sensible
than awk...!), say, you could do an analogous thing with the
dvi2bitmap output, and put the generated
<code>&lt;img&gt;</code> elements in the correct places in
the output HTML file. </p>





<h2><a name="libdvi2bitmap">4 The libdvi2bitmap library</a></h2>


<p>The main bulk of the code which implements <code>dvi2bitmap</code>
is in a library, and the program itself is a rather thin wrapper on
top of this.  This library is intended to be usable for other
applications.</p>

<p>The library is written in C++, and provides an abstraction of DVI
files, PK font files, Bitmaps, and various other objects used to build
these ones.  By default, the build procedure creates both static and
dynamic libraries.</p>

<p>The library API is extensively documented in the
<code>doc_libdvi2bitmap/</code> directory of the
distribution.</p>



<h2><a name="install">5 Building and installing dvi2bitmap</a></h2>


<p>The package uses a automake/autoconf/libtool build system.
Building should therefore be simple:</p>
<pre>
% ./configure
% make
% make install</pre>
<p>

but see the configuration options below.</p>

<p>By default, both a static and a dynamic library are built.  If
there is some reason why building the dynamic library fails on your
platform, configure using <code>--disable-shared</code> and
you'll build a static library only.</p>

<p>It's a good idea to run <code>(cd test;make)</code> as
well.  See <a href="#usage.fonts.finding">2.5.1 Finding fonts</a>.</p> 

<p>To install, just copy the executable
<code>dvi2bitmap</code> wherever you want it to live.</p>

<p>You can customise the program using flags to the
<code>./configure</code> command:</p>
<dl>
<dt>
<code>--with-kpathsea</code> and <code>--without-kpathsea</code>
</dt>
<dd>
<p>If you have the <code>kpathsea</code> library (see
<a href="#usage.fonts.finding">2.5.1 Finding fonts</a>) but don't, for some
reason, want to use it, then give the configure option
<code>--without-kpathsea</code>.  By default, the
configuration enables use of the library if it is
installed (that is, if the <code>kpathsea</code>
include files and library are somewhere the compiler
will find them.  If <code>kpathsea</code> is disabled
(by default or by request), then fonts will not be
generated by default.</p>

<p>If you have the <code>kpathsea</code> library, but it
is not in the standard place, then you can provide an
argument to the <code>--with-kpathsea</code> option
giving the name of a directory below which are
directories <code>include</code> and <code>lib</code>,
containing the required <code>kpathsea</code> include
files and library.


If you don't have the
<code>kpathsea</code> library available, see below
(<a href="#install.web2c">5.1 Obtaining the kpathsea library</a>) for notes on obtaining
it.</p>
</dd>

<dt><code>--disable-texmfcnf</code></dt>
<dd>
<p>The <code>kpathsea</code> library finds its
configuration files in two ways, either automatically
if it is installed in the same directory as the rest
of the TeXware, or using the <code>TEXMFCNF</code>
environment variable.  The <code>dvi2bitmap</code>
program sets the latter variable internally, unless it
finds it already set.  If this will be inconvenient,
you can suppress this behaviour by providing the flag
<code>--disable-texmfcnf</code>, or equivalently
<code>--enable-texmfcnf=no</code>.</p>
</dd>

<dt><a name="conf.enable-fontgen"><code>--enable-fontgen</code></a></dt>
<dd>
<p>The program can attempt to generate fonts, and will
do so using the MetaFont mode <code>ibmvga</code>,
which has a resolution of 110 dots-per-inch.</p>

<p>You can give an argument to this command, which
specifies a command-line which will build and install
a required font, and return its path on standard
output.  This uses the font-string template described
in <a href="#usage.fonts.template">2.5.4 Font-string templates</a>.  You could
duplicate the default (the <code>mktexpk</code> script
if present) with the option</p>
<pre>
--enable-fontgen='&lt;path&gt;mktexpk --dpi %d --bdpi %b --mag %m --mfmode %M %f'</pre>

<p>The default for this option is `on' -- the program
will attempt to generate fonts.  Do note, however,
that if the <code>kpathsea</code> library is not
enabled, then the program will <em>not</em> be able to
find the fonts it generates, unless you configure it
correctly using either <code>-fp</code> or
<code>DVI2BITMAP_PK_PATH</code> (see <a href="#usage.fonts.finding">2.5.1 Finding fonts</a>).</p>

<p>If you wish to disable this automatic font
generation, give the option
<code>--disable-fontgen</code>.  Note that this does
not completely disable font generation -- it merely
sets the default for font generation to `off', and it
can be switched back on again using the option
<code>-fG.</code></p>

<p>If you wish to change the default mode, you can do so
using the option <a href="#conf.fontgen-mode"></a>.</p>
</dd>

<dt><a name="conf.fontgen-mode">
<code>--with-fontgen-mode=mode,res</code></a></dt>
<dd>
<p>If you wish to change the default parameters for
font-generation, you can set both the Metafont mode
and resolution using this option.  For example, the
option <code>--fontgen-mode=pcprevw,118</code> will
make <code>pcprevw</code>, which has a resolution of
118 dpi, the default MetaFont mode.  Note that the
resolution you specify <em>must</em> match the mode:
see file <code>modes.mf</code> for a list of modes and
resolutions (use <kbd>kpsewhich mf modes.mf</kbd> to
find this).  You can change the resolution and mode on
the fly using the <code>-fm</code> and <code>-r</code>
options to the compiled program (<a href="#usage.options">2.1 Options</a>).</p>
</dd>

<dt><a name="conf.with-fontfinder">
<code>--with-fontfinder</code></a></dt>
<dd>
<p>This specifies a command to run to find fonts.  It is
preferable to use the <code>kpathsea</code> library if
possible, but if this is difficult, then you can
specify a script to run to find fonts.  This uses the
font-string template described in <a href="#usage.fonts.template">2.5.4 Font-string templates</a>.  To use the standard
<code>kpsewhich</code> command, for example, you could
give the option</p>
<pre>
--with-fontfinder='/usr/local/teTeX/bin/kpsewhich pk %f.%dpk'
</pre>
</dd>

<dt>
<code>--enable-mktexpk</code> and
<code>--enable-maketexpk</code>
</dt>
<dd>
<p>In the default configuration, the program will
generate missing fonts using one of the standard
scripts present in most TeX distributions.  The
configuration process looks first for
<code>mktexpk</code> then <code>MakeTeXPK</code>, and
uses whichever it finds first.  If you have both
scripts but wish to use <code>MakeTeXPK</code> for
some reason, you will have to give the option
<code>--disable-mktexpk</code>; if you wish to disable
both, you will have to give
<code>--disable-maketexpk</code> as well.  Both
options take an optional argument giving the path to
an alternative script with the same calling interface.</p>
</dd>

<dt>
<code>--with-png</code> (default: enabled)</dt>
<dd>
<p>If you give this option, and if the PNG library is
installed (needs a version after 0.96), then the
program will be compiled with support for PNG bitmaps
as an output format.  You can obtain the PNG library
from the <a href="http://www.libpng.org/pub/png/">PNG home
page</a>.  You can disable the use of PNG with
the option <code>--without-png</code>.</p>
</dd>

<dt>
<code>--enable-gif</code> (default: disabled)</dt>
<dd>
<p>The program generates only XBM bitmaps by default.
If you want it to be able to generate GIFs, then give
the configure option <code>--enable-gif</code>.  The
GIF format is the copyright of CompuServe.  As far as
I understand it, one does not need a licence from
CompuServe if one is distributing non-commercial,
not-for-profit software, such as this.  You probably
shouldn't enable GIF support when you build this
program unless you're in that category as well.  But
don't listen to me: there's a much fuller account of
the whole sorry business in the <a href="ftp://rtfm.mit.edu/pub/usenet/news.answers/graphics/fileformats-faq">Graphics
File Formats FAQ</a> (<a href="http://www.oreilly.com/centers/gff/gff-faq/gff-faq1.htm">HTML</a>).</p>
</dd>

<dt><a name="conf.enable-fake-progname">
<code>--enable-fake-progname</code></a></dt>
<dd>
<p>This option enables a workaround which allows
<code>dvi2bitmap</code> to have the expected behaviour
when (a) you do not install <code>dvi2bitmap</code>
along with the other dvi-ware, <em>and</em> (b) your
<code>texmf.cnf</code> file has
<code>VARTEXFONTS</code> (or a similar variable)
depending on one of the <code>SELFAUTO...</code>
variables (such a <code>texmf.cnf</code> file is
probably broken, but that may not be your problem, or
within your power to fix).  This option makes
<code>dvi2bitmap</code> claim to be a different
DVI-reading program which <em>is</em> installed in the
standard place.  See <a href="#usage.fonts.notfinding">2.5.2 Not finding fonts</a> for discussion.  The
configuration script uses the location of the
<code>xdvi</code> program by default, but you can
override this by giving the full path to an
alternative as an argument to this option (that is,
<code>--enable-fake-progname=/path/to/dviprog</code>). </p>

<p>Since this uses undocumented behaviour of the library
(`use the source, Luke!'), you almost certainly
shouldn't enable it unless you have to.</p>
</dd>

<dt><code>--with-path-seps</code></dt>
<dd>
<p>The default configuration is for Unix, and uses the
Unix defaults for filesystem path and search path
separators.  If you are building it on some other
architecture, you can alter the defaults by giving a
two-character argument to this option, giving the two
separators in order.  For example, the arguments
appropriate for DOS would be</p>
<pre>--with-path-seps='\;'</pre>
</dd>

</dl>

<p>The <code>./configure</code> command without any options is
equivalent to <code>./configure --with-kpathsea --with-png
--enable-mktexpk</code> (meaning that kpathsea and PNG
output will be enabled if library support for them is
found).</p>

<p>The program builds successfully on (at least):</p>
<blockquote>
<table>
<tr>
<th>Platform</th>
<th>Version</th>
<th>Compiler</th>
</tr>

<tr>
<td>powerpc-apple-darwin6.6 (MacOS X, 10.2.6)</td>
<td>0.11b1</td>
<td>g++ 3.1 20020420 (prerelease)</td>
</tr>
<tr>
<td>sun-sparc-solaris2.9</td>
<td>0.11b1</td>
<td>CC: Sun WorkShop 6 update 2 C++ 5.3
2001/05/15</td>
</tr>
<tr>
<td>alphaev67-dec-osf5.1</td>
<td>0.11b1</td>
<td>Compaq C++ V6.5-014</td>
</tr>
<tr>
<td>i686-pc-linux-gnu (RedHat 7.3)</td>
<td>0.11b1</td>
<td>g++ 2.96</td>
</tr>
<tr>
<td>i686-pc-linux-gnu (RedHat 7.3)</td>
<td>0.10</td>
<td>gcc 2.96</td>
</tr>
<tr>
<td>i686-pc-linux-gnu (RedHat 6.2)</td>
<td>0.10b1</td>
<td>egcs-2.91.66</td>
</tr>
<tr>
<td>powerpc-apple-darwin6.4 (MacOSX 10.2)</td>
<td>0.10</td>
<td>g++ 3.1 20020420 (prerelease)</td>
</tr>
<tr>
<td>sparc-sun-solaris2.8</td>
<td>0.10b1</td>
<td>egcs-2.91.66</td>
</tr>
<tr>
<td>alphaev56-dec-osf5.0</td>
<td>0.10b1</td>
<td>egcs-2.91.66</td>
</tr>
<tr>
<td>i686-pc-linux-gnu (RedHat 6.2)</td>
<td>0.9-7p1</td>
<td>egcs-2.91.66</td>
</tr>
<tr>
<td>powerpc-unknown-linux-gnu (Mac mklinux
DR-0.3?)</td>
<td>0.9</td>
<td>egcs-2.90.25 980302 (egcs-1.0.2 prerelease)</td>
</tr>
<tr>
<td>sparc-sun-solaris2.7</td>
<td>0.9</td>
<td>egcs-2.91.66</td>
</tr>
<tr>
<td>sparc-sun-solaris2.7</td>
<td>0.9</td>
<td>gcc 2.8.1</td>
</tr>
<tr>
<td>sparc-sun-solaris2.7</td>
<td>0.9-6</td>
<td>WorkShop Compilers 5.0 98/12/15 C++
5.0</td>
</tr>
<tr>
<td>alpha-dec-osf4.0f</td>
<td>0.9-6</td>
<td>Compaq C++ V6.2-024 for Digital UNIX V4.0F</td>
</tr>
<tr>
<td>i386-pc-solaris2.6</td>
<td>0.9-7p1</td>
<td>gcc v2.8.1/libstdc++ v2.8.1.1</td>
</tr>
</table>
</blockquote>
<p>The `version' column is the last version which was actually tested on
that platform/compiler combination.  Reports of compilations on other
platform/compiler combinations gratefully received.</p>

<p>It should be written in standards-conforming C++, so if it
doesn't build then (1) it's not as conformant as I think it
is (in which case please tell me), (2) your compiler is not
as conformant as you think it is (in which case please don't
tell me), or (3) you need to invoke some magic to get the
compiler to be conformant (in which case tell me, if there's
something I can do in the autoconfigure script).</p>

<p>You can override the C++ compiler the configure script will
choose by setting the environment variable <code>CXX</code>,
either via </p>
<pre>% CXX=cxx ./configure</pre>
<p>
or</p>
<pre>% env CXX=cxx ./configure</pre>
<p>
depending on your shell.</p>

<p>Run regression tests with <code>(cd test;make)</code> in
the build directory.  This includes a separate whole-program
test which additionally gives advice about setting
environment variables.  You can run this script separately
with the command <code>(cd test;make pathtest)</code></p>

<p>Regression test 6 currently fails to link when using Compaq
<code>cxx</code>, for some arcane C++ reason I have yet to
diagnose.  The whole-script test mentioned above works,
though.</p>

<h3><a name="install.web2c">5.1 Obtaining the kpathsea library</a></h3>


<p>Not all TeX distributions install the
<code>kpathsea</code> library, even though they install
applications built with it, and the <code>texmf.cnf</code>
configuration file which controls it.</p>

<p>If the library does not appear to be in your
distribution, then you can obtain and build it yourself.
The library is distributed as part of the
<code>web2c</code> (Unix TeX source) distribution, which
you can find at
<span class="url">ftp://ftp.tug.org/tex/web2c.tar.gz</span>, or mirrored
on CTAN sites (for example at
<span class="url">http://www.tex.ac.uk</span> in directory <code>systems/web2c</code>).</p>

<p>Take a copy of the library (this is a <em>big</em>
distribution), and unpack it.  Go into the
<code>kpathsea</code> directory and do the usual
`<code>./configure; make; make install</code>' routine.
With (some?)  older distributions of the library this
appeared not to work, and you had to go to the parent of
the <code>kpathsea</code> directory, delete the web2c
directory (which is the bulk of the distribution), then
configure and build it as usual, ignoring the warnings
about the missing main <code>texmf</code> tree.</p>





<h2><a name="developments">6 Bugs, extras, and further developments</a></h2>


<p>To report bugs, please send to
<code>norman@astro.gla.ac.uk</code> a brief description of the
problem; a minimal TeX file which reproduces it; some
indication of the machine you're running on (<kbd>uname
-a</kbd> is good); and the output of <kbd>dvi2bitmap -V</kbd>,
which shows the options you have enabled.</p>

<p>See the <code>TODO</code> list in the distribution, for the
list of things I at least would like to see added to the
code.</p>

<p>Bright ideas, fixes and (especially) implementations,
cheerfully received.</p>

<p>In the <code>.../extras</code> directory of the
distribution is a script <code>img-eqlist.pl</code>, which transforms a
file of LaTeX fragments into a LaTeX file, keeping track of
filenames, and avoiding generating duplicate bitmaps for duplicated
maths.</p>



<h2><a name="refs">7 References and acknowledgements</a></h2>


<p>CTAN, the Comprehensive TeX Archive Network, is <em>the</em>
repository of TeX and LaTeX documentation.  The archive is
mirrored in numerous places, but the UK node is at
<span class="url">http://www.tex.ac.uk</span>.</p>

<p>DVItype and PKtoPX are two programs Donald Knuth intended as
model DVI and PK file readers, and as containers for the
canonical documentation of the DVI and PK file formats.  They
might be available as part of your TeX distribution, but are
also available on CTAN, in <code>/tex-archive/systems/knuth/texware/dvitype.web</code>
and <code>/tex-archive/systems/knuth/pxl/pktopx.web</code>.</p>

<p>The <cite>DVI Driver Standard, Level 0</cite> is available on
CTAN, in directory <code>/tex-archive/dviware/driv-standard</code>.  This
incorporates sections of the DVItype documentation.  This
program claims to conform to this standard: if it doesn't,
please let me know.</p>

<p>Thanks for bug reports and other suggestions to <a href="http://www.cis.ohio-state.edu/~gurari/">Eitan
Gurari</a> (heroic tester), Oliver Schurr and Oleg
Bartunov (<code>oleg@sai.msu.su</code>).</p>

<p>Yamabe Kazuharu (<code>tako_da@qc4.so-net.ne.jp</code>)
supplied the writer for XPM bitmaps.</p>



<h2>Appendices</h2>

<h2><a name="sgml.maths">A Maths and SGML/HTML</a></h2>


<ul>
<li>
<p><a href="http://www.w3.org/Math/">W3C's maths
WG</a>.  This covers <a href="http://www.w3.org/TR/REC-MathML/">MathML</a> which is now a W3C Recommendation.  The working group
also supports the <a href="http://lists.w3.org/Archives/Public/www-math/">www-math</a>
mailing list.  </p>

</li>

<li>
<p><a href="http://www.oasis-open.org/cover/topics.html#sgml-math">Maths
special topic at the SGML web page</a> </p>
</li>

<li><p>Also, <a href="http://www.oreilly.com/people/staff/crism/math/">maths
proposal from O'Reilly</a>.  </p></li>

<li><p><a href="http://indy.cs.concordia.ca/mathml/">MathML at
Concordia</a> </p></li>

</ul>

<h3><a name="sgml.maths.latex">A.1 LaTeX maths within HTML</a></h3>


<p>The <em>real</em> issue here (for me at least) is
rendering equations within an HTML document.  There are
several tools available which can do that with different
trade-offs. The most popular method is to write the
equations in a LaTeX document, process it, and then hoik
the equations out of the resulting DVI file somehow
(typically using <code>dvips</code> and a postscript to
gif converter), and display them on the web as gifs.  The
big disadvantage with this is that you get an awful lot of
gifs, and the conversion is rather inefficient.</p>

<p>All this hassle <em>should</em> become irrelevant once we
get browsers which can render MathML directly.</p>

<p>There are reviews of the problems, and some of the tools,
in articles <a href="http://forum.swarthmore.edu/typesetting/index.html"><cite>Maths
Typesetting for the Internet</cite></a>, and <a href="http://hutchinson.belmont.ma.us/tth/mmlreview/"><cite>Comparative
Review of World-Wide-Web Mathematics
Renderers</cite></a>.</p>

<p><a href="http://www.tex.ac.uk/tex-archive/support/latex2html/">LaTeX2HTML</a>
is the granddaddy of these translators -- it parses the
LaTeX using Perl, and spits out HTML, turning maths into
gifs.  It's very robust by now.</p>

<p>John Walker's <a href="http://www.fourmilab.ch/webtools/textogif/textogif.html">textogif</a>
is a Perl program which orchestrates the various tools to
do the conversion via postscript, once you've generated
the DVI file.  It works, but it's <em>terribly</em> slow,
which was the motivation for this program.</p>

<p><a href="http://www.cis.ohio-state.edu/~gurari/TeX4ht/mn.html">TeX4ht</a>
(TeX for Hypertext) uses TeX's own parser, but still
produces equations as gifs.  TeX4ht can also emit MathML
from LaTeX.  The TeX4ht documentation has a useful
collection of resources.  There's an alternative location
for TeX4ht <a href="http://www.tug.org/applications/tex4ht/mn.html">at
TUG</a>.</p>

<p><a href="http://hutchinson.belmont.ma.us/tth/">tth:
TeX to HTML translator</a> (<a href="http://hutchinson.belmont.ma.us/tth/manual.cgi">manual</a>).
<code>tth</code> translates LaTeX maths directly to HTML,
with remarkable success and astonishing speed, and with
good failure strategies.  It works very sweetly, but (a)
requires you to tweak your browser to have it map the
symbol font appropriately, and (b) the resulting HTML
can't be printed legibly.  From the same source is <a href="http://hutchinson.belmont.ma.us/tth/mml/">TtHMML</a>,
which translates (La)TeX to HTML plus MathML.</p>

<p><a href="http://www.nikhef.nl/~t16/public/ndvi/ndvi_doc.html">nDVI</a>
is a DVI viewer plugin for Unix Netscape.  This addresses
the problem at the client end.</p>


<h3><a name="sgml.maths.other">A.2 Other approaches to maths</a></h3>


<p>A quite different approach is to use a different markup
for maths, possibly requiring specialised client software.
These other notations typically use semantic markup --
expressing the structure of the maths.  At first sight,
this seems preferable to LaTeX's presentational markup,
but its weaknesses for authoring are exposed (I feel) when
you realise that maths is not as closed and unambiguous a
language as computer scientists feel it ought to be.
Semantic markup's strength is in interfaces with computer
algebra systems, and databases -- Abramowitz and Stegun
would be ideal in this form!  The major dislocation
between the two approaches is what makes conversion from
presentational to semantic markup so easy.  In passing,
I'll note that MathML has both a presentational and a
semantic variant.</p>

<p><a href="http://www.lfw.org/math/top.html">MINSE</a> uses
a server to render maths into gifs on the fly.  It seems
to work rather nicely, but works with its own semantic
maths notation.</p>

<p>There is (was?) a project called <a href="http://www.dcs.fmph.uniba.sk/~emt/">Euromath</a>,
which includes a structured SGML editor.  This project
included a converter which could transform <a href="http://www.dcs.fmph.uniba.sk/~emt/EmSystem.html#editor">LaTeX
to Euromath SGML</a>.</p>

<p><a href="http://www.nag.co.uk/projects/OpenMath/">OpenMath</a>
might be a successor to Euromath.  It's an EC Esprit
project which `proposes to develop standards for the
semantically-rich representation of mathematics'.</p>

<p><a href="http://www.albany.edu/~hammond/gellmu/">GELLMU</a>
is a LaTeX-like markup language, intended to be easy to
convert to SGML.  Specifically, it is intended to support
maths (and hence conversion to MathML) well.</p>

<p>The following are specifically concerned with maths in
SGML, using either MathML or other maths DTD fragments.</p>

<p><a href="http://www.webeq.com/">WebEQ</a> is a
suite of Java programs which implement MathML.  It's
commercial.</p>

<p><a href="http://www.alphaworks.ibm.com/formula/texml">TeXML</a>
is a gadget from IBM which converts XML to TeX via a DTD
fragment.  You transform your XML to an equivalent
document marked up in TeXML, which you then separately
transform to TeX.</p>

<p><a href="http://www.w3.org/People/Raggett/EzMath">EzMath</a>
is a Dave Raggett proposal for producing maths on the web.
It uses yet another notation, and converts it to online
form using a plugin (no printing, and Windows only, as of
April 1999).</p>





<h2><a name="tex.dimensions">B TeX dimensions</a></h2>


<p>When producing this program, I became terribly confused
about the variety of dimensions which appear in DVI and PK
files.  <a href="#tsizes"></a> is a summary of the sizes which
appear, for the benefit of anyone else attempting a project
like this.  The reference [Dn] refers to section `<img src="doc.img/m-1064.gif">' of the webbed DVItype document
and [Pn] to section `<img src="doc.img/m-1065.gif">' of the
PktoPX document (see <a href="#refs">7 References and acknowledgements</a>).</p>

<p>If you feel I have misunderstood something here, or got one of the
conversion factors wrong (I hate these!), please correct me.</p>

<table>
<caption>Sizes in TeX</caption>
<tr>
<th>Context</th>
<th>Description</th>
<th>See</th>
</tr>
<tr>
<td>DVI preamble</td>
<td>
<code>num</code>, <code>den</code>: multiply
a `DVI unit' by <img src="doc.img/m-1077.gif"> to
obtain a length in units of <img src="doc.img/m-1078.gif">
</td>
<td>[D17]</td>
</tr>
<tr>
<td></td>
<td>
<code>mag</code>: DVI units are actually multiplied by
<img src="doc.img/m-1084.gif">
</td>
<td>[D17]
</td>
</tr>
<tr>
<td>DVI font definition</td>
<td>
<code>d</code>: a design size, in DVI units.
The nominal size of the font.</td>
<td>[D18]</td>
</tr>
<tr>
<td></td>
<td>
<code>s</code>: a `fixed point' scale factor, range
<img src="doc.img/m-1095.gif">,
scaling <code>d</code> (see note).</td>
<td>[D18]</td>
</tr>
<tr>
<td>PK preamble</td>
<td>
<code>ds</code>: the font design size in
units of <img src="doc.img/m-1102.gif">
points.</td>
<td>[P12]</td>
</tr>
<tr>
<td></td>
<td>
<code>hppp</code>, <code>vppp</code>: number
of pixels per point, times <img src="doc.img/m-1109.gif"> (see note).</td> 
<td>[P12]</td>
</tr>
<tr>
<td>Character</td>
<td>
<code>tfmwidth</code>: the width of the
character (see note).</td>
<td>[D37], [P9]</td>
</tr>
<tr>
<td></td>
<td>
<code>w</code>, <code>h</code>: the width and
height, in pixels, of the character pixel map.</td>
<td>[P21]</td>
</tr>
<tr>
<td></td>
<td>
<code>hoff</code> and <code>voff</code>:
offset of the pixel map from the reference point.</td>
<td>[P21]</td>
</tr>
<tr>
<td></td>
<td>
<code>dm</code>, <code>dx</code>,
<code>dy</code>: the pixel
escapements. <code>dm</code> in pixels,
<code>dx</code> and <code>dy</code> in pixels times
<img src="doc.img/m-1137.gif"> (see
note).</td>
<td>[P21]</td>
</tr>

</table>

<ol>
<li>
<p><code>s</code> scales the design size, so that a font
is actually used at <img src="doc.img/m-1143.gif"> 
times its normal size.</p>
</li>

<li>
<p><code>hppp</code> and <code>vppp</code> aren't used
as sizes, but can be used to check you have the right
fonts by comparing resolution, etc..</p>
</li>

<li>
<p><code>tfmwidth</code> is the `physical' size of a
character, and is the only size that TeX uses in its
calculations, and which the DVI reader uses when
working out how far to move the reference point when
it sets a character.  This is defined in [P9] to be in
units of <code>FIXes</code>, where one
<code>FIX</code> is <img src="doc.img/m-1153.gif"> times the design
size in points.  [D37] describes how to multiply these
widths by scaling factors without overflowing.</p>
</li>

<li>
<p>The difference between the pixel escapements and
<code>tfmwidth</code> is that the latter is a
resolution-independent shift of the DVI reference
point, and the former is the PK file's recommendation
of the number of pixels the DVI processor should
actually move.  The DVI processor keeps track of the
two reference points, and readjusts the pixel-based
one when rounding errors move it too far from the
resolution-independent one.  See [D89] and [D91]; also
[D40].</p>
</li>
</ol>

<p>A few useful conversions are:</p>
<ul>
<li>
<p>The design size of a font is a physical length, of <img src="doc.img/m-1161.gif">
points. [P12]</p>
</li>

<li>
<p>A <code>FIX</code> is a physical size, of length
<img src="doc.img/m-1165.gif"></p>
</li>

<li>
<p>A TFM width is a physical size.  The
<code>tfmwidth</code> parameter is in units of
<code>FIXes</code>, so that the TFM width is a length
of <code>tfmwidth</code> fixes, which is equal to <img src="doc.img/m-1171.gif"> points.</p>
</li>

<li>
<p>Writing `dviu' for the unit `DVI units', `sp' for the scaled point
of <img src="doc.img/m-1174.gif"> points, `px'
for pixels, and <img src="doc.img/m-1175.gif"> for
Knuth's deci-micron, or <img src="doc.img/m-1176.gif">, 
<img src="doc.img/m-1177.gif">
</p>
</li>

</ul>



<h2><a name="rn">C Release notes</a></h2>


No changes from 1.0.





</body>
</html>