1 files changed, 635 insertions, 0 deletions
diff --git a/src/utils/afmtodit/afmtodit.1.man b/src/utils/afmtodit/afmtodit.1.man
new file mode 100644
index 0000000..7b0a39f
--- /dev/null
+++ b/src/utils/afmtodit/afmtodit.1.man
@@ -0,0 +1,635 @@
+.TH afmtodit @MAN1EXT@ "@MDATE@" "groff @VERSION@"
+.SH Name
+afmtodit \- adapt Adobe Font Metrics files for
+.I groff
+PostScript and PDF output
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_afmtodit_1_man_C \n[.cp]
+.cp 0
+.
+.\" Define fallback for groff 1.23's MR macro if the system lacks it.
+.nr do-fallback 0
+.if !\n(.f           .nr do-fallback 1 \" mandoc
+.if  \n(.g .if !d MR .nr do-fallback 1 \" older groff
+.if !\n(.g           .nr do-fallback 1 \" non-groff *roff
+.if \n[do-fallback]  \{\
+.  de MR
+.    ie \\n(.$=1 \
+.      I \%\\$1
+.    el \
+.      IR \%\\$1 (\\$2)\\$3
+.  .
+.\}
+.rr do-fallback
+.
+.
+.\" ====================================================================
+.SH Synopsis
+.\" ====================================================================
+.
+.SY afmtodit
+.RB [ \-ckmnsx ]
+.RB [ \-a\~\c
+.IR slant ]
+.RB [ \-d\~\c
+.IR device-description-file ]
+.RB [ \-e\~\c
+.IR encoding-file ]
+.RB [ \-f\~\c
+.IR internal-name ]
+.RB [ \-i\~\c
+.IR italic-correction-factor ]
+.RB [ \-o\~\c
+.IR output-file ]
+.RB [ \-w\~\c
+.IR space-width ]
+.I afm-file
+.I map-file
+.I font-description-file
+.YS
+.
+.
+.SY afmtodit
+.B \-\-help
+.YS
+.
+.
+.SY afmtodit
+.B \-v
+.
+.SY afmtodit
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH Description
+.\" ====================================================================
+.
+.I \%afmtodit
+adapts an
+Adobe Font Metric
+file,
+.IR afm-file ,
+for use with the
+.B ps
+and
+.B pdf
+output devices of
+.MR @g@troff @MAN1EXT@ .
+.
+.I map-file
+associates a
+.I groff
+ordinary or special character name with a PostScript glyph name.
+.
+Output is written in
+.MR groff_font @MAN5EXT@
+format to
+.I font-description-file,
+a file named for the intended
+.I groff
+font name
+(but see the
+.B \-o
+option).
+.
+.
+.LP
+.I map-file
+should contain a sequence of lines of the form
+.
+.RS
+.EX
+.I ps-glyph groff-char
+.EE
+.RE
+.
+where
+.I ps-glyph
+is the PostScript glyph name and
+.I groff-char
+is a
+.I groff
+ordinary
+(if of unit length)
+or special
+(if longer)
+character identifier.
+.
+The same
+.I ps-glyph
+can occur multiple times in the file;
+each
+.I groff-char
+must occur at most once.
+.
+Lines starting with \[lq]#\[rq] and blank lines are ignored.
+.
+If the file isn't found in the current directory,
+it is sought in the
+.I devps/generate
+subdirectory of the default font directory.
+.
+.
+.LP
+If a PostScript glyph is not mentioned in
+.IR map-file ,
+and a
+.I groff
+character name can't be deduced using the Adobe Glyph List
+(AGL,
+built into
+.IR afmtodit ),
+then
+.I \%afmtodit
+puts the PostScript glyph into the
+.I groff
+font description file as an unnamed glyph which can only be accessed
+by the \[lq]\eN\[rq] escape sequence in a
+.I roff
+document.
+.
+In particular,
+this is true for glyph variants named in the form
+.RI \[lq] foo . bar \[rq];
+all glyph names containing one or more periods are mapped to unnamed
+entities.
+.
+Unless
+.B \-e
+is specified,
+the encoding defined in the AFM file
+(i.e.,
+entries
+with non-negative codes)
+is used.
+.
+Refer to section \[lq]Using Symbols\[rq] in
+.IR "Groff: The GNU Implementation of troff" ,
+the
+.I groff
+Texinfo manual,
+or
+.MR groff_char @MAN7EXT@ ,
+which describe how
+.I groff
+character identifiers are constructed.
+.
+.
+.LP
+Glyphs not encoded in the AFM file
+(i.e.,
+entries indexed as \[lq]\-1\[rq])
+are still available in
+.IR groff ;
+they get glyph index values greater than 255
+(or greater than the biggest code used in the AFM file in the unlikely
+case that it is greater than 255)
+in the
+.I groff
+font description file.
+.
+Unencoded glyph indices don't have a specific order;
+it is best to access them only via special character identifiers.
+.
+.
+.P
+If the font file proper
+(not just its metrics)
+is available,
+listing it in the files
+.I @FONTDIR@/\:\%devps/\:\%download
+and
+.I @FONTDIR@/\:\%devpdf/\:\%download
+enables it to be embedded in the output produced by
+.MR grops @MAN1EXT@
+and
+.MR gropdf @MAN1EXT@ ,
+respectively.
+.
+.
+.P
+If the
+.B \-i
+option is used,
+.I \%afmtodit
+automatically generates an italic correction,
+a left italic correction,
+and a subscript correction for each glyph
+(the significance of these is explained in
+.MR groff_font @MAN5EXT@ );
+they can be specified for individual glyphs by
+adding to the
+.I afm-file
+lines of the form:
+.
+.RS
+.EX
+.RI italicCorrection \~ps-glyph\~n
+.RI leftItalicCorrection \~ps-glyph\~n
+.RI subscriptCorrection \~ps-glyph\~n
+.EE
+.RE
+.
+where
+.I ps-glyph
+is the PostScript glyph name,
+and
+.I n
+is the desired value of the corresponding parameter in thousandths of an
+em.
+.
+Such parameters are normally needed only for italic
+(or oblique)
+fonts.
+.
+.
+.P
+The
+.B \-s
+option should be given if the font is \[lq]special\[rq],
+meaning that
+.I groff
+should search it whenever a glyph is not found in the current font.
+.
+In that case,
+.I font-description-file
+should be listed as an argument to the
+.B fonts
+directive in the output device's
+.I DESC
+file;
+if it is not special,
+there is no need to do so,
+since
+.MR @g@troff @MAN1EXT@
+will automatically mount it when it is first used.
+.
+.
+.br
+.ne 7v
+.\" ====================================================================
+.SH Options
+.\" ====================================================================
+.
+.B \-\-help
+displays a usage message,
+while
+.B \-v
+and
+.B \%\-\-version
+show version information;
+all exit afterward.
+.
+.
+.TP
+.BI \-a\~ slant
+Use
+.I slant
+as the slant (\[lq]angle\[rq]) parameter in the font description file;
+this is used by
+.I groff
+in the positioning of accents.
+.
+By default
+.I \%afmtodit
+uses the negative of the
+.B \%ItalicAngle
+specified in the AFM file;
+with true italic fonts it is sometimes desirable to use a slant that is
+less than this.
+.
+If you find that an italic font places accents over base glyphs
+too far to the right,
+use
+.B \-a
+to give it a smaller slant.
+.
+.
+.TP
+.B \-c
+Include comments in the font description file identifying the PostScript
+font.
+.
+.
+.TP
+.BI \-d\~ device-description-file
+The device description file is
+.I desc-file
+rather than the default
+.IR DESC .
+.
+If not found in the current directory,
+the
+.I devps
+subdirectory of the default font directory is searched
+(this is true for both the default device description file and a file
+given with option
+.BR \-d ).
+.
+.
+.TP
+.BI \-e\~ encoding-file
+The PostScript font should be reencoded to use the encoding described
+in
+.IR enc-file .
+.
+The format of
+.I enc-file
+is described in
+.MR grops @MAN1EXT@ .
+.
+If not found in the current directory,
+the
+.I devps
+subdirectory of the default font directory is searched.
+.
+.
+.TP
+.BI \-f\~ internal-name
+The internal name of the
+.I groff
+font is set to
+.IR name .
+.
+.
+.TP
+.BI \-i\~ italic-correction-factor
+Generate an italic correction for each glyph so that its width plus its
+italic correction is equal to
+.I italic-correction-factor
+thousandths of an em
+plus the amount by which the right edge of the glyph's bounding box is
+to the right of its origin.
+.
+If this would result in a negative italic correction,
+use a zero italic correction instead.
+.
+.
+.IP
+Also generate a subscript correction equal to the
+product of the tangent of the slant of the font and
+four fifths of the x-height of the font.
+.
+If this would result in a subscript correction greater than the italic
+correction,
+use a subscript correction equal to the italic correction instead.
+.
+.
+.IP
+Also generate a left italic correction for each glyph equal to
+.I italic-correction-factor
+thousandths of an em
+plus the amount by which the left edge of the glyph's bounding box is to
+the left of its origin.
+.
+The left italic correction may be negative unless option
+.B \-m
+is given.
+.
+.
+.IP
+This option is normally needed only with italic
+(or oblique)
+fonts.
+.
+The font description files distributed with
+.I groff
+were created using an option of
+.B \-i50
+for italic fonts.
+.
+.
+.TP
+.BI \-o\~ output-file
+Write to
+.I output-file
+instead of
+.I font-description-file.
+.
+.
+.TP
+.B \-k
+Omit any kerning data from the
+.I groff
+font;
+use only for monospaced (constant-width) fonts.
+.
+.
+.TP
+.B \-m
+Prevent negative left italic correction values.
+.
+Font description files for roman styles distributed with
+.I groff
+were created with
+.RB \[lq] \-i0\~\-m \[rq]
+to improve spacing with
+.MR @g@eqn @MAN1EXT@ .
+.
+.
+.TP
+.B \-n
+Don't output a
+.B ligatures
+command for this font;
+use with monospaced (constant-width) fonts.
+.
+.
+.TP
+.B \-s
+Add the
+.B special
+directive to the font description file.
+.
+.
+.TP
+.BI \-w\~ space-width
+Use
+.I space-width
+as the with of inter-word spaces.
+.
+.
+.TP
+.B \-x
+Don't use the built-in Adobe Glyph List.
+.
+.
+.\" ====================================================================
+.SH Files
+.\" ====================================================================
+.
+.TP
+.I @FONTDIR@/\:\%devps/\:DESC
+describes the
+.B ps
+output device.
+.
+.
+.TP
+.IR @FONTDIR@/\:\%devps/ F
+describes the font known
+.RI as\~ F
+on device
+.BR ps .
+.
+.
+.TP
+.I @FONTDIR@/\:\%devps/\:\%download
+lists fonts available for embedding within the PostScript document
+(or download to the device).
+.
+.
+.TP
+.I @FONTDIR@/\:\%devps/\:\%generate/\:\%dingbats.map
+.TQ
+.I @FONTDIR@/\:\%devps/\:\%generate/\:\%dingbats\-reversed.map
+.TQ
+.I @FONTDIR@/\:\%devps/\:\%generate/\:\%slanted\-symbol.map
+.TQ
+.I @FONTDIR@/\:\%devps/\:\%generate/\:\%symbol.map
+.TQ
+.I @FONTDIR@/\:\%devps/\:\%generate/\:\%text.map
+map names in the Adobe Glyph List to
+.I groff
+special character identifiers for Zapf Dingbats
+.RB ( ZD ),
+reversed Zapf Dingbats
+.RB ( ZDR ),
+slanted symbol
+.RB ( SS ),
+symbol
+.RB ( S ),
+and text fonts,
+respectively.
+.
+These
+.IR map-file s
+are used to produce the font description files provided with
+.I groff
+for the
+.I \%grops
+output driver.
+.
+.
+.\" ====================================================================
+.SH Diagnostics
+.\" ====================================================================
+.
+.TP
+.RI "AGL name \[aq]" x "\[aq] already mapped to groff name \[aq]" y\c
+.RI "\[aq]; ignoring AGL name \[aq]uni" XXXX \[aq]
+You can disregard these if they're in the form shown,
+where the ignored AGL name contains four hexadecimal digits
+.IR XXXX .
+.
+The Adobe Glyph List (AGL) has its own names for glyphs;
+they are often
+different from
+.IR groff 's
+special character names.
+.
+.I \%afmtodit
+is constructing a mapping from
+.I groff
+special character names to AGL names;
+this can be a one-to-one or many-to-one mapping,
+but one-to-many will not work,
+so
+.I \%afmtodit
+discards the excess mappings.
+.
+For example,
+if
+.I x
+is
+.BR *D ,
+.I y
+is
+.BR \%Delta ,
+and
+.I z
+is
+.BR uni0394 ,
+.I \%afmtodit
+is telling you that the
+.I groff
+font description that it is writing cannot map the
+.I groff
+special character
+.B \[rs][*D]
+to AGL glyphs
+.B \%Delta
+and
+.B uni0394
+at the same time.
+.
+.
+.IP
+If you get a message like this but are unhappy with which mapping is
+ignored,
+a remedy is to craft an alternative
+.I map-file
+and re-run
+.I \%afmtodit
+using it.
+.
+.
+.\" ====================================================================
+.SH "See also"
+.\" ====================================================================
+.
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual.
+.
+Section \[lq]Using Symbols\[rq] may be of particular note.
+.
+You can browse it interactively with \[lq]info \[aq](groff)Using
+\%Symbols\[aq]\[rq].
+.
+.
+.LP
+.MR groff @MAN1EXT@ ,
+.MR gropdf @MAN1EXT@ ,
+.MR grops @MAN1EXT@ ,
+.MR groff_font @MAN5EXT@
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[*groff_afmtodit_1_man_C]
+.do rr *groff_afmtodit_1_man_C
+.
+.
+.\" Local Variables:
+.\" fill-column: 72
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff textwidth=72: