[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 08/10: addftinfo: Improve diagnostics and man page.
From: |
G. Branden Robinson |
Subject: |
[groff] 08/10: addftinfo: Improve diagnostics and man page. |
Date: |
Tue, 28 Apr 2020 11:59:27 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 2a4c8d7475f61f9056c0a25b5ae68843e3c7fbe7
Author: G. Branden Robinson <address@hidden>
AuthorDate: Wed Apr 29 00:33:49 2020 +1000
addftinfo: Improve diagnostics and man page.
* src/utils/addftinfo/addftinfo.cpp (usage): Add overloaded version that
accepts a constant string argument, which emits the argument as a
diagnostic and then calls usage().
(main): Add diagnostics to usage message where the problem is clear.
Add comment explaining why it sometimes isn't.
(usage): Refactor main usage message (which prints the summary) to
report the actual names of the accepted option arguments instead of
just "-param", which is not literally accepted.
Sort param_table alphabetically for use by the usage message.
Tidy up long lines and whitespace.
Tested with:
addftinfo -1 -2 /dev/null
addftinfo -asc-height 1 -body-depth 2 3
addftinfo -asc-height 1 -body-depth 2 3 4
addftinfo -asc-height 1 -body-depth 2 3 4 /dev/null
addftinfo /dev/null
addftinfo 1
addftinfo 1 -2 /dev/null
addftinfo 1 /dev/null
addftinfo 1 2 /dev/null
addftinfo 1 2 3
* src/utils/addftinfo/addftinfo.1.man: Condense summary.
Delete unused string definition for ellipsis.
Use English words and phrases for parameter names.
Document --help and --version.
Sort option list alphabetically.
Make minor clarifications.
Save and restore compatibility mode since we now use groff extensions
(\~ and \[]-form character escapes).
---
ChangeLog | 30 ++++++++-
src/utils/addftinfo/addftinfo.1.man | 131 +++++++++++++++++++++---------------
src/utils/addftinfo/addftinfo.cpp | 58 ++++++++++------
3 files changed, 141 insertions(+), 78 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 7d5e032..ff121c1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,30 @@
+2020-04-29 G. Branden Robinson <address@hidden>
+
+ * src/utils/addftinfo/addftinfo.cpp (usage): Add overloaded
+ version that accepts a constant string argument, which emits the
+ argument as a diagnostic and then calls usage().
+ (main): Add diagnostics to usage message where the problem is
+ clear. Add comment explaining why it sometimes isn't.
+ (usage): Refactor main usage message (which prints the summary)
+ to report the actual names of the accepted option arguments
+ instead of just "-param", which is not literally accepted.
+
+ Sort param_table alphabetically for use by the usage message.
+
+ Tidy up long lines and whitespace.
+
+ Tested with:
+ addftinfo -1 -2 /dev/null
+ addftinfo -asc-height 1 -body-depth 2 3
+ addftinfo -asc-height 1 -body-depth 2 3 4
+ addftinfo -asc-height 1 -body-depth 2 3 4 /dev/null
+ addftinfo /dev/null
+ addftinfo 1
+ addftinfo 1 -2 /dev/null
+ addftinfo 1 /dev/null
+ addftinfo 1 2 /dev/null
+ addftinfo 1 2 3
+
2020-04-22 G. Branden Robinson <address@hidden>
Delete groffer.
@@ -6193,7 +6220,8 @@ notice and this notice are preserved.
##### Editor settings
Local Variables:
+fill-column: 72
mode: change-log
version-control: never
End:
-vim:set autoindent:
+vim:set autoindent textwidth=72:
diff --git a/src/utils/addftinfo/addftinfo.1.man
b/src/utils/addftinfo/addftinfo.1.man
index dac73cf..04c5b1e 100644
--- a/src/utils/addftinfo/addftinfo.1.man
+++ b/src/utils/addftinfo/addftinfo.1.man
@@ -1,6 +1,11 @@
.TH addftinfo @MAN1EXT@ "@MDATE@" "groff @VERSION@"
.SH Name
-addftinfo \- add information to troff font files for use with groff
+addftinfo \- add font metrics to troff fonts for use with groff
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_addftinfo_1_man_C \n[.cp]
+.cp 0
.
.
.\" ====================================================================
@@ -26,16 +31,6 @@ addftinfo \- add information to troff font files for use
with groff
.
.
.\" ====================================================================
-.\" Characters
-.\" ====================================================================
-.
-.\" Ellipsis ...
-.ie t .ds EL \fS\N'188'\fP\"
-.el .ds EL \&.\|.\|.\&\"
-.\" called with \*(EL
-.
-.
-.\" ====================================================================
.SH Synopsis
.\" ====================================================================
.
@@ -48,8 +43,8 @@ addftinfo \- add information to troff font files for use with
groff
.OP \-desc\-depth n
.OP \-fig\-height n
.OP \-x\-height n
-.I res
-.I unitwidth
+.I resolution
+.I unit-width
.I font
.YS
.
@@ -68,107 +63,131 @@ addftinfo \- add information to troff font files for use
with groff
.SH Description
.\" ====================================================================
.
-.B addftinfo
-reads a troff font file and adds some additional font-metric
-information that is used by the groff system.
+.I addftinfo
+reads an
+.RI AT&T \~troff
+font file
+.IR font ,
+adds additional font metric information required by
+.IR groff ,
+and writes the combined result to the standard output.
.
-The font file with the information added is written on the standard
-output.
+The information added is guessed using some parametric information about
+the font and assumptions about the traditional
+.I troff
+names for characters.
.
-The information added is guessed using some parametric information
-about the font and assumptions about the traditional troff names for
-characters.
-.
-The main information added is the heights and depths of characters.
+Among the font metrics added are the heights and depths of characters
+(how far each extends vertically above and below the baseline).
.
The
-.I res
+.I resolution
and
-.I unitwidth
+.I unit-width
arguments should be the same as the corresponding parameters in the
-DESC file;
+.I DESC
+file.
+.
.I font
is the name of the file describing the font;
if
.I font
ends with
-.B I
-the font will be assumed to be italic.
+.RB \[lq] I \[rq],
+the font is assumed to be italic.
.
.
.\" ====================================================================
.SH Options
.\" ====================================================================
.
+.B \-\-help
+displays a usage message,
+while
.B \-v
-prints the version number.
+and
+.B \-\-version
+show version information;
+all exit afterward.
.
.
.LP
All other options change one of the parameters that are used to derive
the heights and depths.
.
-Like the existing quantities in the font file, each
+Like the existing quantities in the font file,
+each
.I value
is in
-.RI inches/ res
+.RI inches/ resolution
for a font whose point size is
-.IR unitwidth .
+.IR unit-width .
.
-.I param-option
-must be one of:
.
.TP
-.B \-x\-height
-The height of lowercase letters without ascenders such as x.
+.BI \-asc\-height \~n
+The height of characters with ascenders,
+such as \[lq]b\[rq], \[lq]d\[rq], or \[lq]l\[rq].
.
-.TP
-.B \-fig\-height
-The height of figures (digits).
.
.TP
-.B \-asc\-height
-The height of characters with ascenders, such as b, d or l.
+.BI \-body\-depth \~n
+The depth of characters such as parentheses.
+.
.
.TP
-.B \-body\-height
+.BI \-body\-height \~n
The height of characters such as parentheses.
.
+.
.TP
-.B \-cap\-height
-The height of uppercase letters such as A.
+.BI \-cap\-height \~n
+The height of uppercase letters such as \[lq]A\[rq].
+.
.
.TP
-.B \-comma\-depth
+.BI \-comma\-depth \~n
The depth of a comma.
.
+.
.TP
-.B \-desc\-depth
-The depth of characters with descenders, such as p, q, or y.
+.BI \-desc\-depth \~n
+The depth of characters with descenders,
+such as \[lq]p\[rq], \[lq]q\[rq], or \[lq]y\[rq].
+.
.
.TP
-.B \-body\-depth
-The depth of characters such as parentheses.
+.B \-fig\-height
+The height of figures (digits, numerals).
+.
+.
+.TP
+.BI \-x\-height \~n
+The height of lowercase letters without ascenders such as \[lq]x\[rq].
.
.
.LP
-.B addftinfo
+.I addftinfo
makes no attempt to use the specified parameters to guess the
unspecified parameters.
.
-If a parameter is not specified the default will be used.
+If a parameter is not specified,
+the default will be used.
.
-The defaults are chosen to have the reasonable values for a Times
-font.
+The defaults are chosen to have reasonable values for a Times font.
.
.
.\" ====================================================================
.SH "See Also"
.\" ====================================================================
.
-.BR groff_font (@MAN5EXT@),
-.BR groff (@MAN1EXT@),
-.BR groff_char (@MAN7EXT@)
+.IR groff_font (@MAN5EXT@),
+.IR groff (@MAN1EXT@),
+.IR groff_char (@MAN7EXT@)
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[*groff_addftinfo_1_man_C]
.
.
.\" Local Variables:
diff --git a/src/utils/addftinfo/addftinfo.cpp
b/src/utils/addftinfo/addftinfo.cpp
index 4211c59..7e63b9d 100644
--- a/src/utils/addftinfo/addftinfo.cpp
+++ b/src/utils/addftinfo/addftinfo.cpp
@@ -33,6 +33,7 @@ extern "C" const char *Version_string;
static void usage(FILE *stream);
static void usage();
+static void usage(const char *problem);
static void version();
static void convert_font(const font_params &, FILE *, FILE *);
@@ -42,14 +43,14 @@ static struct {
const char *name;
param_t par;
} param_table[] = {
- { "x-height", &font_params::x_height },
- { "fig-height", &font_params::fig_height },
{ "asc-height", &font_params::asc_height },
+ { "body-depth", &font_params::body_depth },
{ "body-height", &font_params::body_height },
{ "cap-height", &font_params::cap_height },
{ "comma-depth", &font_params::comma_depth },
{ "desc-depth", &font_params::desc_depth },
- { "body-depth", &font_params::body_depth },
+ { "fig-height", &font_params::fig_height },
+ { "x-height", &font_params::x_height },
};
// These are all in thousandths of an em.
@@ -77,17 +78,20 @@ int main(int argc, char **argv)
}
}
if (argc < 4)
- usage();
+ usage("insufficient arguments");
+ /* The next couple of usage() calls cannot provide a meaningful
+ diagnostic because we don't know whether sscanf() failed on a
+ required parameter or an option. A refactor could fix this. */
int resolution;
if (sscanf(argv[argc-3], "%d", &resolution) != 1)
usage();
if (resolution <= 0)
- fatal("resolution must be > 0");
+ fatal("resolution must be positive");
int unitwidth;
if (sscanf(argv[argc-2], "%d", &unitwidth) != 1)
usage();
if (unitwidth <= 0)
- fatal("unitwidth must be > 0");
+ fatal("unit width must be positive");
font_params param;
const char *font = argv[argc-1];
param.italic = (font[0] != '\0' && strchr(font, '\0')[-1] == 'I');
@@ -106,7 +110,7 @@ int main(int argc, char **argv)
break;
}
if (i + 1 >= argc)
- usage();
+ usage("option requires argument");
size_t j;
for (j = 0;; j++) {
if (j >= sizeof(param_table)/sizeof(param_table[0]))
@@ -115,11 +119,11 @@ int main(int argc, char **argv)
break;
}
if (sscanf(argv[i+1], "%d", &(param.*(param_table[j].par))) != 1)
- fatal("invalid argument '%1'", argv[i+1]);
+ fatal("invalid option argument '%1'", argv[i+1]);
i++;
- }
+ }
if (argc - i != 3)
- usage();
+ usage("insufficient arguments");
errno = 0;
FILE *infp = fopen(font, "r");
if (infp == 0)
@@ -130,16 +134,27 @@ int main(int argc, char **argv)
static void usage(FILE *stream)
{
- fprintf(stream, "usage: %s [-v] [-param value] ... "
- "resolution unitwidth font\n",
- program_name);
+ fprintf(stream, "usage: %s", program_name);
+ size_t len = sizeof(param_table)/sizeof(param_table[0]);
+ for (int i = 0; i < len; i++)
+ fprintf(stream, " [-%s N]", param_table[i].name);
+ fprintf(stream, " RESOLUTION UNIT-WIDTH FONT\n");
+ fprintf(stream, "%s -v\n", program_name);
+ fprintf(stream, "%s --version\n", program_name);
}
+
static void usage()
{
usage(stderr);
exit(1);
}
+static void usage(const char *problem)
+{
+ error("%1", problem);
+ usage();
+}
+
static void version()
{
printf("GNU addftinfo (groff) version %s\n", Version_string);
@@ -157,8 +172,9 @@ static int get_line(FILE *fp, string *p)
}
return p->length() > 0;
}
-
-static void convert_font(const font_params ¶m, FILE *infp, FILE *outfp)
+
+static void convert_font(const font_params ¶m, FILE *infp,
+ FILE *outfp)
{
string s;
while (get_line(infp, &s)) {
@@ -200,18 +216,18 @@ static void convert_font(const font_params ¶m, FILE
*infp, FILE *outfp)
printf(",%d,%d", metric.height, metric.depth);
}
else
- printf(",%d,%d,%d", metric.height, metric.depth, metric.ic);
+ printf(",%d,%d,%d", metric.height, metric.depth,
+ metric.ic);
}
else
- printf(",%d,%d,%d,%d", metric.height, metric.depth, metric.ic,
- metric.left_ic);
+ printf(",%d,%d,%d,%d", metric.height, metric.depth,
+ metric.ic, metric.left_ic);
}
else
- printf(",%d,%d,%d,%d,%d", metric.height, metric.depth, metric.ic,
- metric.left_ic, metric.sk);
+ printf(",%d,%d,%d,%d,%d", metric.height, metric.depth,
+ metric.ic, metric.left_ic, metric.sk);
}
}
fputs(p, outfp);
}
}
-
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 08/10: addftinfo: Improve diagnostics and man page.,
G. Branden Robinson <=