summaryrefslogtreecommitdiff
path: root/support/mf2pt1/mf2pt1.texi
blob: 9260689d18cf1acdb82ad06e7c23b8a17d5cd73d (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
\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename mf2pt1.info
@settitle mf2pt1
@setchapternewpage off
@dircategory TeX
@direntry
* mf2pt1: (mf2pt1).   PostScript Type 1 fonts from Metafont source.
@end direntry
@finalout
@c %**end of header

@copying
Copyright @copyright{} 2005--2021 Scott Pakin

@sp 2

This program may be distributed and/or modified under the conditions
of the @LaTeX{} Project Public License, either version 1.3c of this
license or (at your option) any later version.

@sp 1

The latest version of this license is in:
@sp 1
@center @uref{https://www.latex-project.org/lppl.txt}
@sp 1
and version 1.3c or later is part of all distributions of @LaTeX{}
version 2006/05/20 or later.

@end copying

@set VERSION 2.7
@set DATE 4 December 2021

@c Define some fonts we intend to use.
@iftex
@tex
@global@font@tenlogo=logo10 % font used for the METAFONT logo
@global@font@eightrm=cmr8   % needed for the "A" in "LaTeX"
@end tex
@end iftex

@c Define a macro for the Metafont logo.
@iftex
@macro MF {}
@tex
@tenlogo @leavevmode@hbox{METAFONT}@unskip
@end tex
@end macro
@end iftex
@ifnottex
@macro MF {}
Metafont
@end macro
@end ifnottex

@macro copt {option}
@w{@code{--\option\}}
@end macro

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@iftex
@tex
% If we're using pdfTeX in PDF-generating mode then include some
% document metadata.
\ifx\pdfoutput\undefined
\else
  \ifx\pdfoutput\relax
  \else
    \ifcase\pdfoutput
    \else
      \pdfinfo {
        /Title    (mf2pt1)
        /Subject  (Produce PostScript Type 1 fonts from Metafont source)
        /Author   (Scott Pakin <scott+mf@@pakin.org>)
        /Keywords (PostScript Type 1 fonts, Metafont, MetaPost, FontForge)
      }
    \fi
  \fi
\fi
@end tex
@end iftex

@titlepage
@title mf2pt1
@subtitle Produce PostScript @w{Type 1} fonts from Metafont source
@author Scott Pakin, @email{scott+mf@@pakin.org}

@page

@vskip 0pt plus 2filll

This file documents @command{mf2pt1} version @value{VERSION}, dated
@value{DATE}.

@vskip 0pt plus 1filll

@insertcopying

@contents

@end titlepage

@ifnottex
@node Top, Introduction, (dir), (dir)
@top mf2pt1

@command{mf2pt1} is a tool that lets font designers design PostScript
@w{Type 1} fonts using the @MF{} language.  The same source file can be
used to produce both @w{Type 1} (@file{.pfb}) and bitmap (@file{.pk})
fonts.
@end ifnottex

@menu
* Introduction::                Introduction to mf2pt1
* Usage::                       How to use mf2pt1
* Future Work::                 Features I may one day add to mf2pt1
* Acknowledgments::             People who helped with mf2pt1
@end menu


@node Introduction, Usage, Top, Top
@chapter Introduction

@MF{} is a high-level, mathematically oriented language for producing
fonts.  The @MF{} interpreter produces device-dependent bitmaps, which
render well at the target resolution on the target device, but poorly
at other resolutions or on other devices.  Adobe's PostScript @w{Type 1}
font format is the de facto font standard for printers these days.  It
is a vector format, which implies that it scales better than bitmaps,
and it delegates the device- and resolution-dependent tweaking from
the font source to the target device's PostScript renderer.  However,
@w{Type 1} fonts are extremely difficult to code by hand.  Usually, one
uses a @acronym{WYSIWYG} program to design a @w{Type 1} font.  @MF{}, with
its font-specific programming language, is an elegant alternative.  A
font designer can write reusable subroutines for repeated features,
such as serifs and accents.  He can define a font in terms of
arbitrary parameters, such as ``boldness'' or ``italicness'', making
it trivial to produce entire families of fonts from a single source
(hence the ``meta'' in the name ``@MF{}'').  Ideally, we would like to
design a font using the @MF{} language, but produce PostScript @w{Type 1}
output instead of bitmaps.

@command{mf2pt1} helps bridge the gap between @MF{} and @w{Type 1} fonts.
@command{mf2pt1} facilitates producing PostScript @w{Type 1} fonts from a
@MF{} source file.  It is @emph{not}, as the name may imply, an
automatic converter of arbitrary @MF{} fonts to @w{Type 1} format.
@command{mf2pt1} imposes a number of restrictions on the @MF{} input.
If these restrictions are met, @command{mf2pt1} will produce valid
@w{Type 1} output.

@menu
* Requirements::                Pre-installation checklist
* Installation::                How to install mf2pt1
@end menu


@node Requirements, Installation, Introduction, Introduction
@section Requirements

Before using @command{mf2pt1}, you will need to install the following
programs:

@table @asis
@item Perl
@command{mf2pt1} is written in Perl.  You will need a Perl interpreter
to run it.

@item MetaPost
@command{mf2pt1} actually uses MetaPost, not @MF{}, to produce
PostScript output.  Specifically, you will need the @command{mpost}
executable and the @file{mfplain.mp} base file.

@item @w{Type 1} Utilities
Producing properly encoded @w{Type 1} fonts is tricky.
@command{mf2pt1} delegates the effort to the @w{Type 1} Utilities,
specifically, to the @command{t1asm} program within that suite.

@item FontForge (optional)
FontForge is a @acronym{WYSIWYG}, but scriptable, @w{Type 1}
font-editing program.  Although FontForge is not strictly required for
@command{mf2pt1} to produce a @w{Type 1} font, @command{mf2pt1} uses
FontForge when available to autohint the generated @w{Type 1} font,
thereby making it look better especially at lower resolutions.
@end table

Perl is available from @uref{https://www.cpan.org, the Comprehensive
Perl Archive Network}; MetaPost and the @w{Type 1} utilities are
available from @uref{https://www.ctan.org, the Comprehensive @TeX{}
Archive Network}; and FontForge is available from
@uref{https://fontforge.sourceforge.net/}.  In addition, MetaPost's
home page is @uref{https://tug.org/metapost.html}, and the @w{Type 1}
utilities' home page is @uref{https://www.lcdf.org/type/}.

Besides being useful for autohinting fonts, FontForge enables a font
designer to hint fonts manually for additional fine-tuning and to
convert among a variety of font formats, such as PostScript, TrueType,
and @w{X Window} fonts.  FontForge is strongly recommended as a
complement to @command{mf2pt1}.


@node Installation,  , Requirements, Introduction
@section Installation

To install @command{mf2pt1}, move the @file{mf2pt1} executable
someplace where your operating system can find it.  If you're running
Microsoft Windows, you should rename the program to @file{mf2pt1.pl},
so that Windows knows it's a Perl script.  (Alternatively, if you have
@command{pl2bat}, use that to produce a @file{mf2pt1.bat} file, which
you can run as simply @file{mf2pt1}.)

The next step is to produce a @file{mf2pt1.mem} file from the supplied
@file{mf2pt1.mp}.  The command to do this differs from system to
system but is usually something like the following:

@example
mpost -progname=mpost -ini mf2pt1 \\dump
@end example

Move the resulting @file{mf2pt1.mem} file someplace where MetaPost can
find it.

@sp 1

The @command{mf2pt1} documentation (what you're reading now) is written
in Texinfo and can therefore easily be converted to a variety of
formats:

@table @asis
@item PDF (@file{mf2pt1.pdf})
@example
texi2pdf mf2pt1.texi
@end example

@item PostScript (@file{mf2pt1.ps})
@example
texi2dvi mf2pt1.texi
dvips mf2pt1.dvi -o mf2pt1.ps
@end example

@item HTML (@file{mf2pt1.html})
@example
makeinfo --html mf2pt1.texi
@end example

@item Info (@file{mf2pt1.info})
@example
makeinfo mf2pt1.texi
@end example
@end table

@noindent
N.B@.  The @command{install-info} command is a convenient way to install
@file{mf2pt1.info} on your system.

@sp 1

On Unix, you may also want to generate an @command{mf2pt1} man page.
The man page is embedded within the @file{mf2pt1} Perl script and can be
extracted with @command{pod2man}:

@example
pod2man --center="User Commands" --date="@value{DATE}" \
  --release="v@value{VERSION}" mf2pt1 > mf2pt1.1
@end example

@noindent
You can then move @file{mf2pt1.1} into @file{/usr/man/man1} or any other
man page directory.  Note that the @command{mf2pt1} man page is fairly
rudimentary.  It is primarily a list of the command-line options
(@pxref{Font information}) and a pointer to the document that you're
reading now.


@node Usage, Future Work, Introduction, Top
@chapter Usage

@command{mf2pt1} is fairly straightforward to use.  To process a
@MF{} source file, merely specify the filename:

@example
mf2pt1 myfont.mf
@end example

@noindent
That simple command automatically performs all of the following
operations:

@enumerate
@item
Read @file{myfont.mf}.

@item
Use @command{mpost} to convert each character to a separate
Encapsulated PostScript (@acronym{EPS}) file named
@file{myfont.@var{num}}.

@item
Process and merge the @acronym{EPS} files into a single
``disassembled'' @w{Type 1} font called @file{myfont.pt1}.

@item
Run @command{t1asm} from the @w{Type 1} Utilities to convert the
disassembled font into a true, binary @w{Type 1} font called
@file{myfont.pfb}.

@item
Invoke @command{fontforge} to apply rendering hints to
@file{myfont.pfb} and to attempt to remove overlapping paths.
@end enumerate

The external programs launched by @command{mf2pt1}---@command{mpost},
@command{t1asm}, and @command{fontforge}---can be overridden by
setting the eponymous, uppercase environment variable.  For example,
invoking FontForge's predecessor, PfaEdit, instead of FontForge is
simply a matter of setting the @samp{FONTFORGE} environment variable
to @samp{pfaedit} before invoking @command{mf2pt1}.  As a corollary,
you can inhibit an @command{mf2pt1} external program from running by
setting the corresponding environment variable to the name of a
nonexistent program.  Arguments can be included in the environment
variable's value.  Hence, defining @samp{MPOST} to @samp{mpost
-recorder}, for instance, instructs @command{mf2pt1} to run
@command{mpost} with the @samp{-recorder} option.

@menu
* Restrictions::                Restrictions imposed on the font source code
* Font information::            Specifying PostScript font characteristics
* Additional command-line options::  Options unrelated to font characteristics
* Custom font encodings::       Altering the mapping from character name to number
* Restoring mfplain defaults::  Using the original (un)filldraw and pencircle
@end menu


@node Restrictions, Font information, Usage, Usage
@section Restrictions

If @command{mf2pt1} sounds too good to be true, it is---somewhat.
@command{mf2pt1} is not a general-purpose @MF{}-to-@w{Type 1}
converter.  Rather, it can convert only certain @MF{} constructs.
This is not a showstopper for new fonts designed with @command{mf2pt1}
in mind, but it is unlikely that @command{mf2pt1} will work on an
arbitrary @MF{} source file.

@command{mf2pt1}'s biggest restriction is that each glyph must be
drawn entirely from closed paths, using @MF{}'s @strong{fill} and
@strong{unfill} commands.  (@command{mf2pt1} has limited support for
@strong{draw} and @strong{undraw}, but their use is currently
discouraged.  @strong{filldraw} and @strong{unfilldraw} issue a
warning message and invoke @strong{draw} and @strong{undraw},
respectively.)  The @w{Type 1} format requires that these paths be
nonoverlapping.  The following are some of the alternatives for
removing path overlaps:

@enumerate
@item
Install FontForge.  As part of its final step in producing a @w{Type
1} font, @command{mf2pt1} instructs FontForge to replace overlapping
paths with nonoverlapping paths.

@item
Remove overlaps using @MF{} code within the font program itself.  A
@file{.zip} file attachment to
@uref{https://tug.org/pipermail/metapost/2005-January/000080.html,
a @w{6 January} 2005 article} by
@iftex
@tex
Bogus\l{}aw
@end tex
@end iftex
@ifnottex
Boguslaw
@end ifnottex
Jackowski on the MetaPost mailing list (subject: ``Re: all
intersections between two paths'') includes a MetaPost library which
assists with that task.  The library provides a @strong{find_outlines}
command which can be used to define a path as the union of two other
paths.  A number of MetaPost example programs are also included in the
@file{.zip} file.

@item
Design your fonts from the beginning without using overlapping paths.
@end enumerate

A secondary restriction is that @command{mf2pt1} redefines a number of
Plain @MF{} commands, such as @strong{beginchar}, @strong{fill}, and
@strong{unfill}.  @MF{} font programs which redefine or bypass these
(using @MF{} primitives) will not be convertible with
@command{mf2pt1}.

A far less severe restriction is due to @command{mf2pt1}'s utilizing
MetaPost's @MF{} interface instead of @MF{} itself.  The implication
is that commands not defined by MetaPost's @file{mfplain.mp} cannot be
handled by @command{mf2pt1}, either.  Very few fonts will have a
problem with this restriction but see the MetaPost manual for more
information.


@node Font information, Additional command-line options, Restrictions, Usage
@section Specifying font information

@iftex
@tex
@leavevmode
@end tex
@end iftex
@MF{} fonts normally specify a set of @strong{fontdimen}s which
provide information about a particular font that cannot otherwise be
inferred.  These include features such as the font's x-height, quad
width, interword stretchability and shrinkability, and other design
characteristics that @TeX{} makes use of.  PostScript fonts utilize a
largely different set of font parameters, such as the underline
position and thickness, font family name, and copyright notice.
@command{mf2pt1} provides @MF{} commands to define the PostScript font
parameters in the generated @w{Type 1} font.  These parameters should
appear in the @MF{} source file as follows:

@display
@b{if} known @i{ps_output}:
  @dots{}
@b{fi}
@end display

@noindent
@code{ps_output} is defined by @command{mf2pt1} but not by Plain
@MF{}.  Checking if it is known is the recommended way to determine if
the font is being built under @command{mf2pt1}.

@ifnottex
@menu
* Parameters::                  Font-information commands available to Metafont
* Command-line equivalents::    Specifying font features on the command line
* Default values::              Types and default values of each parameter
* Parameter example::           Metafont example which specifies all parameters
@end menu


@node Parameters, Command-line equivalents, Font information, Font information
@subsection Parameters
@end ifnottex

The following list presents all of the font-information commands
provided by @command{mf2pt1} and describes what each command means.
Commands marked with an asterisk are also defined by Plain @MF{} and
therefore do not need to be enveloped within a test for
@code{ps_output}.

@table @strong
@item font_coding_scheme
The mapping between character numbers and PostScript names.  If this
is the name of a file, @command{mf2pt1} expects it to contain
PostScript code defining a font-encoding vector.  @xref{Custom font
encodings}, for an example of such a file.  If
@strong{font_coding_scheme} is not the name of a file,
@command{mf2pt1} expects it to be one of the literal strings
@code{standard} (Adobe standard encoding), @code{isolatin1} (ISO Latin
1 encoding), @code{ot1} (@TeX{} 7-bit encoding), @code{t1} (@TeX{}
8-bit encoding), or @code{asis} (encoding integrated with the
character programs using the @strong{glyph_name} command as described
in @ref{Custom font encodings}).  Anything else will generate a
warning message and cause @command{mf2pt1} to use @code{standard}
instead.

@item font_comment
A textual comment that will appear within the generated font.  This is
often used for copyright notices.

@item font_family
The family that this font belongs to.  For example, ``Utopia Bold
Italic'' belongs to the @code{Utopia} family.

@item font_fixed_pitch
Whether the font is monospaced (if @strong{true}) or or proportionally
spaced (if @strong{false}).

@item font_identifier (*)
The full name of the font, e.g., @code{Utopia Bold Italic}.

@item font_name
The symbolic font name, used to load the font from a PostScript
document.  Spaces are forbidden.  Generally, the font name is of the
form @code{@var{family}-@var{modifiers}}.  For example, the font name
of Utopia Bold Italic would be @code{Utopia-BoldItalic}.

@item font_size (*)
The font design size.  This is specified in ``sharped'' units within
@MF{} code or as a point size on the command line.

@item font_slant (*)
When specified with @strong{font_slant}, the amount of slant per
point.  When specified with @copt{italicangle}, the angle in
counterclockwise degrees from the vertical (i.e., zero for an upright
font, negative for a right-slanting italic font).

@item font_underline_position
The vertical position at which an underline should lie, specified in
``sharped'' units within @MF{} code or as a number of points on the
command line.

@item font_underline_thickness
The thickness of an underline, specified in ``sharped'' units within
@MF{} code or as a number of points on the command line.

@item font_unique_id
The unique ID for this font.  The ID should be between 0 and
16,777,215, with the ``open'' range being 4,000,000-4,999,999.  All
IDs not in that range are allocated by contacting Adobe's UniqueID
Coordinator.  (I don't believe a fee is involved, but I don't know for
sure.)  If a unique ID is not specified, @command{mf2pt1} will not
write a unique ID to the file.  Note that Adobe no longer recommends
including unique IDs in fonts.

@item font_version
The version number of the font.  This should be of the form
@code{@var{MMM}.@var{mmm}}, where @var{MMM} is the major version
number and @var{mmm} is the minor version number.

@item font_weight
The font weight.  For example, the font weight of Utopia Bold Italic
is @code{Bold}.
@end table


@ifnottex
@node Command-line equivalents, Default values, Parameters, Font information
@subsection Command-line equivalents
@end ifnottex

Each of the
@iftex
preceding font-information commands
@end iftex
@ifnottex
font-information commands listed in @ref{Parameters}
@end ifnottex
has a command-line equivalent.  Their use is discouraged but they are
listed here for completeness:

@multitable {@strong{font_underline_thickness}} {@copt{fontversion}}
@item
@strong{font_coding_scheme}
@tab @copt{encoding}

@item
@strong{font_comment}
@tab @copt{comment}

@item
@strong{font_family}
@tab @copt{family}

@item
@strong{font_fixed_pitch}
@tab @copt{fixedpitch}

@item
@strong{font_identifier}
@tab @copt{fullname}

@item
@strong{font_name}
@tab @copt{name}

@item
@strong{font_size}
@tab @copt{designsize}

@item
@strong{font_slant}
@tab @copt{italicangle}

@item
@strong{font_underline_position}
@tab @copt{underpos}

@item
@strong{font_underline_thickness}
@tab @copt{underthick}

@item
@strong{font_unique_id}
@tab @copt{uniqueid}

@item
@strong{font_version}
@tab @copt{fontversion}

@item
@strong{font_weight}
@tab @copt{weight}
@end multitable

A special case is @copt{fixedpitch} which does not take an argument.
Rather, you should use @copt{fixedpitch} as the equivalent of
@samp{font_fixed_pitch true} and @copt{nofixedpitch} as the equivalent
of @samp{font_fixed_pitch false}.


@ifnottex
@node Default values, Parameter example, Command-line equivalents, Font information
@subsection Default values
@end ifnottex

The next table lists the @MF{} type and default value of each of the
parameters listed in
@ifnottex
@ref{Parameters}.
@end ifnottex
@ifnotinfo
the previous table.
@end ifnotinfo

@multitable {@strong{font_underline_thickness}} {@strong{numeric}} {MMMMMMMMMMMMMMMMMMMMMMMMM}
@item @strong{font_coding_scheme}
@tab  @strong{string}
@tab  @code{"standard"}

@item @strong{font_comment}
@tab  @strong{string}
@tab  @code{"Font converted to @w{Type 1} by mf2pt1, written by Scott Pakin."}

@item @strong{font_family}
@tab  @strong{string}
@tab  (The value of @strong{font_identifier})

@item @strong{font_fixed_pitch}
@tab  @strong{boolean}
@tab  @strong{false}

@item @strong{font_identifier}
@tab  @strong{string}
@tab  (The input filename, minus @file{.mf})

@item @strong{font_name}
@tab  @strong{string}
@tab  (The value of @strong{font_family}, plus an underscore, plus the
      value of @strong{font_weight}, with all spaces removed)

@item @strong{font_size}
@tab  @strong{numeric}
@tab  (Must be specified or @command{mf2pt1} will abort with an error message)

@item @strong{font_slant}
@tab  @strong{numeric}
@tab  0

@item @strong{font_underline_position}
@tab  @strong{numeric}
@tab  -1

@item @strong{font_underline_thickness}
@tab  @strong{numeric}
@tab  0.5

@item @strong{font_unique_id}
@tab  @strong{string}
@tab  (Randomly generated in the range 4000000-4999999)

@item @strong{font_version}
@tab  @strong{string}
@tab  @code{"001.000"}

@item @strong{font_weight}
@tab  @strong{string}
@tab  @code{"Medium"}
@end multitable

@sp 1


@ifnottex
@node Parameter example,  , Default values, Font information
@subsection Parameter example
@end ifnottex

As an example, the following @MF{} code shows the usage of all of the
parameters that @command{mf2pt1} accepts:

@noindent
@b{if} known @i{ps_output}:
@multitable {@b{if}} {@b{font_underline_thickness}} {@t{"Copyright (C) 2021 Scott Pakin.";}}
@item @tab @b{font_coding_scheme}       @tab @t{"ot1"};
@item @tab @b{font_comment}             @tab @t{"Copyright (C) 2021 Scott Pakin."};
@item @tab @b{font_family}              @tab @t{"Kerplotz"};
@item @tab @b{font_fixed_pitch}         @tab @b{false};
@item @tab @b{font_identifier}          @tab @t{"Kerplotz Light Oblique"};
@item @tab @b{font_name}                @tab @t{"Kerplotz-LightOblique"};
@item @tab @b{font_size}                @tab 10@i{pt}#; @ @ @ @ @ % Important to include this.
@item @tab @b{font_slant}               @tab 1/6;
@item @tab @b{font_underline_position}  @tab -1@i{pt}#;
@item @tab @b{font_underline_thickness} @tab 1/2@i{pt}#;
@item @tab @b{font_unique_id}           @tab @t{"4112233"}; @ @ @ @ @ % Better to omit this.
@item @tab @b{font_version}             @tab @t{"002.005"};
@item @tab @b{font_weight}              @tab @t{"Light"};
@end multitable
@noindent
@b{fi}

@noindent
In the above, the @strong{font_fixed_pitch} call could have been
omitted, as it defaults to @strong{false}.  Also, unless you've
requested a unique ID from Adobe, it's generally better not to assign
@strong{font_unique_id}; let @command{mf2pt1} choose a random value
itself.

The same parameters can also be specified on the command line as
follows:

@example
mf2pt1 --encoding=ot1 --comment="Copyright (C) 2021 Scott Pakin."
  --family=Kerplotz --nofixedpitch --fullname="Kerplotz Light Oblique"
  --name=Kerplotz-LightOblique --designsize=10 --italicangle=-9.5
  --underpos=-100 --underthick=50 --uniqueid=4112233 --version=002.005
  --weight=Light kerplotz.mf
@end example

@noindent
Note that a @MF{} font slant of 1/6 is equal to a PostScript italic
angle of approximately -9.5.  The conversion formula is
@iftex
@tex
$s = -@tan @theta$, in which $s$ is the slant and $@theta$ is the
italic angle.
@end tex
@end iftex
@ifnottex
slant = -tan(angle).
@end ifnottex
In addition, the underline position and thickness must be multiplied by
1000/@strong{font_size} to convert from the @MF{} units that are used
within the @file{.mf} file to the PostScript units that are used on the
command line.


@node Additional command-line options, Custom font encodings, Font information, Usage
@section Additional command-line options

In addition to the command-line options for setting font parameters
that were presented in
@iftex
@ref{Font information},
@end iftex
@ifnottex
@ref{Parameters},
@end ifnottex
@command{mf2pt1} supports a @copt{rounding} option.  While
@command{mf2pt1} normally rounds all font coordinates to the nearest
integer, @copt{rounding} increases coordinate precision by
instructing @command{mf2pt1} to round instead to the nearest multiple
of a given fractional number.  For example, @samp{--rounding=0.25}
rounds the coordinate @math{(7.4, 10.3)} to @math{(7.5, 10.25)} while
it would otherwise be rounded to the less-precise @math{(7, 10)}.

Large glyphs can be problematic in MetaPost and therefore in
@command{mf2pt1}.  Unlike @MF{}, MetaPost does not honor @samp{mag}
for magnifying dimensions.  Rather, the number of PostScript
(a.k.a. ``big'') points per pixel---@samp{bpppix}---is hardwired @w{to
0.02} and all other dimensions (@samp{mm}, @samp{in}, @samp{pt},
etc.@:) are expressed in terms of that.  Consequently, glyphs that
multiply a large number of font units by a dimension are likely to
exceed 4096, the largest value that MetaPost can represent in its
fixed-point format.  If numerical overflow becomes a problem you can
use the @copt{bpppix} option to @command{mf2pt1} to change the value
of @samp{bpppix}.  For example, specifying @samp{--bpppix=0.2} enables
a tenfold increase in maximum glyph size (with a corresponding
decrease in precision).

After generating a @w{Type 1} font, @command{mf2pt1} runs it through
FontForge to add hinting information, remove overlaps, and otherwise
clean up the generated font.  The @copt{ffscript} option specifies
the filename of a FontForge script to use instead of the default
script, which is listed below:

@example
Open($1);
SelectAll();
RemoveOverlap();
AddExtrema();
Simplify(0, 2);
CorrectDirection();
Simplify(0, 2);
RoundToInt();
AutoHint();
Generate($1);
Quit(0);
@end example

@noindent
See the FontForge documentation for an explanation of each of those
commands and a description of other commands made available to
FontForge scripts.  @command{mf2pt1} runs the script with one argument
(@code{$1}), which is the name of the generated @file{.pfb} file.

@command{mf2pt1} also supports a @copt{help} option which summarizes
all of the program's command-line options.

@c Improve formatting by keeping the large cartouche on the same
@c page as the text that introduces it.
@page

@node Custom font encodings, Restoring mfplain defaults, Additional command-line options, Usage
@section Custom font encodings

@iftex
@ref{Font information},
@end iftex
@ifnottex
@ref{Parameters},
@end ifnottex
lists the font encodings currently supported by @command{mf2pt1} and
mentions that an alternate encoding can be specified by providing the
name of an encoding file.  To elaborate, the following example
represents the contents of an encoding file which defines a---largely
useless nowadays---@acronym{EBCDIC} font encoding:

@cartouche
@quotation
@code{% Sample encoding vector: @acronym{EBCDIC}@*
@*
% The encoding vector must have a name and be defined as a PostScript array.@*
/ebcdic_encoding [@*
/_a0 /_a1 /_a2 /_a3 /_a4 /_a5 /_a6 /_a7 /_a8 /_a9 /_a10 /_a11 /_a12
/_a13 /_a14 /_a15 /_a16 /_a17 /_a18 /_a19 /_a20 /_a21 /_a22 /_a23
/_a24 /_a25 /_a26 /_a27 /_a28 /_a29 /_a30 /_a31 /_a32 /_a33 /_a34
/_a35 /_a36 /_a37 /_a38 /_a39 /_a40 /_a41 /_a42 /_a43 /_a44 /_a45
/_a46 /_a47 /_a48 /_a49 /_a50 /_a51 /_a52 /_a53 /_a54 /_a55 /_a56
/_a57 /_a58 /_a59 /_a60 /_a61 /_a62 /_a63 /space /_a65 /_a66 /_a67
/_a68 /_a69 /_a70 /_a71 /_a72 /_a73 /bracketleft /period /less
/parenleft /plus /exclam /ampersand /_a81 /_a82 /_a83 /_a84 /_a85
/_a86 /_a87 /_a88 /_a89 /bracketright /dollar /asterisk /parenright
/semicolon /asciicircum /hyphen /slash /_a98 /_a99 /_a100 /_a101
/_a102 /_a103 /_a104 /_a105 /bar /comma /percent /underscore /greater
/question /_a112 /_a113 /_a114 /_a115 /_a116 /_a117 /_a118 /_a119
/_a120 /_a121 /colon /numbersign /at /quoteright /equal /quotedbl
/_a128 /a /b /c /d /e /f /g /h /i /_a138 /_a139 /_a140 /_a141 /_a142
/_a143 /_a144 /j /k /l /m /n /o /p /q /r /_a154 /_a155 /_a156 /_a157
/_a158 /_a159 /_a160 /asciitilde /s /t /u /v /w /x /y /z /_a170 /_a171
/_a172 /_a173 /_a174 /_a175 /_a176 /_a177 /_a178 /_a179 /_a180 /_a181
/_a182 /_a183 /_a184 /quoteleft /_a186 /_a187 /_a188 /_a189 /_a190
/_a191 /braceleft /A /B /C /D /E /F /G /H /I /_a202 /_a203 /_a204
/_a205 /_a206 /_a207 /braceright /J /K /L /M /N /O /P /Q /R /_a218
/_a219 /_a220 /_a221 /_a222 /_a223 /backslash /_a225 /S /T /U /V /W /X
/Y /Z /_a234 /_a235 /_a236 /_a237 /_a238 /_a239 /zero /one /two /three
/four /five /six /seven /eight /nine /_a250 /_a251 /_a252 /_a253
/_a254 /_a255@*
% Don't forget to end the array.@*
] def}
@end quotation
@end cartouche

All entries in the encoding vector are PostScript ``names'' and
therefore must be prefixed with a slash.  Unnamed characters such as
control characters are commonly named @samp{_a@var{number}}, where
@var{number} is the decimal offset into the character table.
Undefined characters are indicated by @samp{.notdef}.  In the
@acronym{EBCDIC} example, the character at @w{position 0} in the font
will be named @samp{a0}; the character at @w{position 1} will be named
@samp{a1}; the character at @w{position 74} will be named
@samp{bracketleft}; the character at @w{position 129} will be named
@samp{a}; and so forth.

Individual characters can be mapped to an encoding either numerically
or by executing a @strong{glyph_name} command within a character
definition.  For example, the following code overrides the character
position passed to @strong{beginchar} @w{(i.e., 123)} with whatever
character position the current encoding has designated for the
@samp{ohungarumlaut} glyph:

@display
@b{beginchar} (123, cap_height#-1/2pt#, cap_height#, 0);
  @b{if} known @i{ps_output}:
    @i{glyph_name} @t{"ohungarumlaut"};
  @b{fi}
  @dots{}
@b{endchar};
@end display


@node Restoring mfplain defaults,  , Custom font encodings, Usage
@section Restoring @file{mfplain} defaults

@command{mf2pt1} normally redefines @strong{filldraw} as @strong{fill}
and @strong{unfilldraw} and @strong{unfill} because @w{Type 1} fonts
don't allow overlapping curves.  Similarly, @command{mf2pt1} redefines
@strong{pencircle} as a 20-gon to coerce MetaPost into drawing it
using a filled instead of a stroked PostScript path.

If you know you'll be postprocessing your fonts using FontForge, which
can automatically convert overlapping paths to nonoverlapping paths,
then you can restore the original @file{mfplain.mp} definitions of
@strong{filldraw}, @strong{unfilldraw}, and @strong{pencircle} as
follows:

@display
@b{if} known @i{ps_output}:
  @b{pencircle} := @i{mfplain_pencircle};
  @b{let filldraw} := @i{mfplain_filldraw};
  @b{let unfilldraw} := @i{mfplain_unfilldraw};
@b{fi}
@end display


@node Future Work, Acknowledgments, Usage, Top
@chapter Future Work

One avenue for future work is to enable the font designer to specify
@w{Type 1} font hints directly in the @MF{} font program.  Hinting is
a way for a font designer to specify how a font should be rendered at
low resolutions, for example, at typical monitor resolutions.  In
@MF{}, this is done by controlling the way that points are mapped to
pixel locations, using commands such as
@strong{define_corrected_pixels}, @strong{define_blacker_pixels}, and
@strong{lowres_fix}.  @w{Type 1} fonts are hinted in a completely
different manner.  @w{Type 1} hints distinguish key character
features, such as stems and dots, from decorations which can be
discarded at low resolutions.  The PostScript interpreter uses that
information to determine how to map points to pixels.  Although
@command{mf2pt1} employs FontForge to autohint the fonts it generates,
the approach is mechanical and unlikely to hint as well as a human can
do manually.  It would be convenient for @command{mf2pt1} one day to
provide @MF{} commands for @strong{hstem}, @strong{vstem},
@strong{dotsection}, and the other @w{Type 1} hints.  That way, hints
will no longer need to be re-added manually every time
@command{mf2pt1} regenerates a @w{Type 1} font.

Another future addition to @command{mf2pt1} is the addition of more
font encodings.  The following are the encodings that @command{mf2pt1}
will most likely accept:

@table @code
@item TeXMathItalicEncoding
Upper- and lowercase Greek and Latin letters, old-style digits, and a
few symbols and accents.

@item TeXMathSymbolEncoding
A variety of symbols, as well as calligraphic Latin majuscules.

@item TeXMathExtensionEncoding
Variable-sized symbols, such as braces, integrals, and radicals.

@item AdobeExpert
Small caps, currency symbols, old-style digits, and various superior and
inferior letters and digits.
@end table


@node Acknowledgments,  , Future Work, Top
@unnumbered Acknowledgments

Many thanks are owed to Werner Lemberg for writing the code underlying
the @copt{rounding} option; for introducing the @strong{glyph_name}
command and @code{asis} encoding vector; for providing the default
FontForge script listed in @ref{Additional command-line options}; for
fixing some code-generation bugs in @command{mf2pt1}; for finding a
more robust way to dump @file{mf2pt1.mem}; for directing me to the
overlap-removal code mentioned in @ref{Restrictions}; for supplying
the @emph{crossproduct}, @emph{makeline}, and @emph{is_clockwise}
functions used by @file{mf2pt1.mp}; for proposing the @copt{bpppix}
command-line option; and for suggesting various features and
improvements to @command{mf2pt1}.  Thanks also go to Werner Lemberg
and
@iftex
@tex
Bogus\l{}aw
@end tex
@end iftex
@ifnottex
Boguslaw
@end ifnottex
Jackowski for updating the @strong{is_clockwise} function in
@file{mf2pt1.mp} to work around a bug in MetaPost which relates to the
@strong{turningnumber} command.  Finally, thanks go to Ralf Stubner
for providing the T1 encoding vector and for pointing out a typo in
the generated font programs; to Michael Zedler for alerting me to
problems with @copt{encoding} and suggesting I modify that option to
accept PostScript @file{.enc} files; and to Michael Ummels for fixing
a couple of bugs that made character widths in the generated fonts
slightly too large.

@bye