[groff] 03/32: afmtodit(1): Add "Diagnostics" section.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 0c4ba6d0ad93de79c08ab9b42d17aef6c4dc80f4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jun 14 01:09:04 2023 -0500

    afmtodit(1): Add "Diagnostics" section.
---
 src/utils/afmtodit/afmtodit.1.man | 63 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/src/utils/afmtodit/afmtodit.1.man 
b/src/utils/afmtodit/afmtodit.1.man
index 3a8ce06ab..7b0a39f2c 100644
--- a/src/utils/afmtodit/afmtodit.1.man
+++ b/src/utils/afmtodit/afmtodit.1.man
@@ -538,6 +538,69 @@ 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"
 .\" ====================================================================
 .