diff options
Diffstat (limited to '')
| -rw-r--r-- | src/utils/afmtodit/afmtodit.1.man | 635 |
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: |