Module Name: src
Committed By: rillig
Date: Sat Aug 26 13:52:10 UTC 2023
Modified Files:
src/usr.bin/error: error.1 main.c
Log Message:
error: move comment above the main function to the manual page
While here, clean up the markup of the manual page, removing unnecessary
emphasis.
To generate a diff of this commit:
cvs rdiff -u -r1.21 -r1.22 src/usr.bin/error/error.1
cvs rdiff -u -r1.23 -r1.24 src/usr.bin/error/main.c
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/usr.bin/error/error.1
diff -u src/usr.bin/error/error.1:1.21 src/usr.bin/error/error.1:1.22
--- src/usr.bin/error/error.1:1.21 Sat Aug 26 11:35:56 2023
+++ src/usr.bin/error/error.1 Sat Aug 26 13:52:10 2023
@@ -1,4 +1,4 @@
-.\" $NetBSD: error.1,v 1.21 2023/08/26 11:35:56 rillig Exp $
+.\" $NetBSD: error.1,v 1.22 2023/08/26 13:52:10 rillig Exp $
.\"
.\" Copyright (c) 1980, 1990, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -29,7 +29,7 @@
.\"
.\" @(#)error.1 8.1 (Berkeley) 6/6/93
.\"
-.Dd June 6, 2016
+.Dd August 26, 2023
.Dt ERROR 1
.Os
.Sh NAME
@@ -40,8 +40,8 @@
.Op Fl nqSsTv
.Op Fl I Ar ignorefile
.Op Fl p Ar filelevel
-.Op Fl t Ar suffixlist
-.Op name
+.Op Fl t Ar suffixes
+.Op Ar name
.Sh DESCRIPTION
.Nm
analyzes and optionally disperses the diagnostic error messages
@@ -54,20 +54,26 @@ without machinations of multiple windows
.Pp
Options are:
.Bl -tag -width XpXfilelevelXX
+.It Fl I Ar ignorefile
+The
+.Ar ignorefile Po default: Pa ~/.errorrc Pc
+contains a list of function names
+that are not to be treated as hard errors.
.It Fl n
Do
.Em not
-touch any files; all error messages are sent to the
-standard output.
+touch any files; all error messages are sent to the standard output.
.It Fl p Ar filelevel
Interpret filelevel as a level of path component names to skip,
similar to
.Xr patch 1 .
.It Fl q
-The user is
-.Ar queried
-whether s/he wants to touch the file.
-A ``y'' or ``n'' to the question is necessary to continue.
+Query the user whether to touch the files.
+A
+.Ql y
+or
+.Ql n
+to the question is necessary to continue.
Absence of the
.Fl q
option implies that all referenced files
@@ -76,28 +82,30 @@ are to be touched.
.It Fl S
Show the errors in unsorted order (as they come from the error file).
.It Fl s
-Print out
-.Em statistics
-regarding the error categorization.
+Print out statistics regarding the error categorization.
Not too useful.
.It Fl T
Terse output.
-.It Fl t
-Take the following argument as a suffix list.
-Files whose suffixes do not appear in the suffix list are not touched.
-The suffix list is dot separated, and ``*'' wildcards work.
-Thus the suffix list:
-.Pp
-.Dl ".c.y.foo*.h"
-.Pp
+.It Fl t Ar suffixes
+Only files whose suffix appears in the suffix list are touched.
+The suffix list is dot-separated, and
+.Ql *
+wildcards work.
+Thus the suffix list
+.Ql .c.y.foo*.h
allows
.Nm
-to touch files ending with ``.c'', ``.y'', ``.foo*'' and ``.h''.
+to touch files ending with
+.Ql .c ,
+.Ql .y ,
+.Ql .foo*
+and
+.Ql .h .
.It Fl v
After all files have been touched,
overlay the visual editor
.Xr \&vi 1
-with it set up to edit all files touched,
+with it, set up to edit all files touched,
and positioned in the first touched file at the first error.
If
.Xr \&vi 1
@@ -128,8 +136,7 @@ touches source files only after all inpu
.Pp
.Nm
is intended to be run
-with its standard input
-connected via a pipe to the error message source.
+with its standard input connected via a pipe to the error message source.
Some language processors put error messages on their standard error file;
others put their messages on the standard output.
Hence, both error sources should be piped together into
@@ -151,7 +158,8 @@ syntax
will analyze all the error messages produced
by whatever programs
.Xr make 1
-runs when making lint.
+runs when making
+.Ar lint .
.Pp
.Nm
knows about the error messages produced by:
@@ -171,11 +179,9 @@ and
knows a standard format for error messages produced by
the language processors,
so is sensitive to changes in these formats.
-For all languages except
-.Em Pascal ,
+For all languages except Pascal,
error messages are restricted to be on one line.
-Some error messages refer to more than one line in more than
-one files;
+Some error messages refer to more than one line in more than one file;
.Nm
will duplicate the error message and insert it at
all of the places referenced.
@@ -220,17 +226,14 @@ or from the file named by the
option.
If the file does not exist,
no error messages are nullified.
-If the file does exist, there must be one function
-name per line.
+If the file does exist, there must be one function name per line.
.It Em not file specific
Error messages that can't be intuited are grouped together,
and written to the standard output before any files are touched.
They will not be inserted into any source file.
.It Em file specific
-Error message that refer to a specific file,
-but to no specific line,
-are written to the standard output when
-that file is touched.
+Error message that refer to a specific file, but to no specific line,
+are written to the standard output when that file is touched.
.It Em true errors
Error messages that can be intuited are candidates for
insertion into the file to which they refer.
@@ -241,19 +244,22 @@ the file they refer to.
Other error messages are consumed entirely by
.Nm
or are written to the standard output.
+.Pp
.Nm
inserts the error messages into the source file on the line
preceding the line the language processor found in error.
Each error message is turned into a one line comment for the
language,
-and is internally flagged
-with the string ``###'' at
-the beginning of the error,
-and ``%%%'' at the end of the error.
+and is internally flagged with the string
+.Ql ###
+at the beginning of the error, and
+.Ql %%%
+at the end of the error.
This makes pattern searching for errors easier with an editor,
and allows the messages to be easily removed.
In addition, each error message contains the source line number
for the line the message refers to.
+.Pp
A reasonably formatted source program can be recompiled
with the error messages still in it,
without having the error messages themselves cause future errors.
@@ -261,9 +267,8 @@ For poorly formatted source programs in
such as C or Pascal,
it is possible to insert a comment into another comment,
which can wreak havoc with a future compilation.
-To avoid this, programs with comments and source
-on the same line should be formatted
-so that language statements appear before comments.
+To avoid this, programs with comments and source on the same line
+should be formatted so that language statements appear before comments.
.Pp
.Nm
catches interrupt and terminate signals,
@@ -304,13 +309,12 @@ initiated by one syntactically trivial e
Humans are still much better at discarding these related errors.
.Pp
Pascal error messages belong after the lines affected
-(error puts them before). The alignment of the `\e' marking
-the point of error is also disturbed by
+(error puts them before). The alignment of the
+.Ql ^
+marking the point of error is also disturbed by
.Nm .
.Pp
.Nm
-was designed for work on
-.Tn CRT Ns 's
-at reasonably high speed.
+was designed for work on CRTs at reasonably high speed.
It is less pleasant on slow speed terminals, and has never been
used on hardcopy terminals.
Index: src/usr.bin/error/main.c
diff -u src/usr.bin/error/main.c:1.23 src/usr.bin/error/main.c:1.24
--- src/usr.bin/error/main.c:1.23 Sat Aug 26 11:35:56 2023
+++ src/usr.bin/error/main.c Sat Aug 26 13:52:10 2023
@@ -1,4 +1,4 @@
-/* $NetBSD: main.c,v 1.23 2023/08/26 11:35:56 rillig Exp $ */
+/* $NetBSD: main.c,v 1.24 2023/08/26 13:52:10 rillig Exp $ */
/*
* Copyright (c) 1980, 1993
@@ -39,7 +39,7 @@ __COPYRIGHT("@(#) Copyright (c) 1980, 19
#if 0
static char sccsid[] = "@(#)main.c 8.1 (Berkeley) 6/6/93";
#endif
-__RCSID("$NetBSD: main.c,v 1.23 2023/08/26 11:35:56 rillig Exp $");
+__RCSID("$NetBSD: main.c,v 1.24 2023/08/26 13:52:10 rillig Exp $");
#endif /* not lint */
#include <signal.h>
@@ -84,43 +84,6 @@ static void forkvi(int, char **);
static void try(const char *, int, char **);
static void usage(void) __attribute__((__noreturn__));
-/*
- * error [-nqSsTv] [-I <ignorename>] [-t <suffixlist>] [-p <level>] <infile>
- *
- * -I: the following name, `ignorename' contains a list of
- * function names that are not to be treated as hard errors.
- * Default: ~/.errorsrc
- *
- * -n: don't touch ANY files!
- *
- * -p: take the next argument as the number of levels to skip
- * from the filename, like patch.
- *
- * -q: The user is to be queried before touching each
- * file; if not specified, all files with hard, non
- * ignorable errors are touched (assuming they can be).
- *
- * -S: show the errors in unsorted order
- * (as they come from the error file)
- *
- * -s: print a summary of the error's categories.
- *
- * -T: terse output
- *
- * -t: touch only files ending with the list of suffixes, each
- * suffix preceded by a dot.
- * eg, -t .c.y.l
- * will touch only files ending with .c, .y or .l
- *
- * -v: after touching all files, overlay vi(1), ex(1) or ed(1)
- * on top of error, entered in the first file with
- * an error in it, with the appropriate editor
- * set up to use the "next" command to get the other
- * files containing errors.
- *
- * infile: The error messages come from this file.
- * Default: stdin
- */
int
main(int argc, char **argv)
{
