386BSD 0.1 development

[unix-history] / usr / src / usr.bin / mkstr / mkstr.1

diff --git a/usr/src/usr.bin/mkstr/mkstr.1 b/usr/src/usr.bin/mkstr/mkstr.1
index 737057c..bc5fc30 100644 (file)
--- a/usr/src/usr.bin/mkstr/mkstr.1
+++ b/usr/src/usr.bin/mkstr/mkstr.1
@@ -1,94 +1,137 @@
-.\" Copyright (c) 1980 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1980, 1990 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)mkstr.1     5.1 (Berkeley) %G%
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.

 .\"
 .\"

-.TH MKSTR 1 "24 February 1979"
-.UC
-.SH NAME
-mkstr \- create an error message file by massaging C source
-.SH SYNOPSIS
-.B mkstr
-[
-.B \-
-]
-messagefile prefix file ...
-.SH DESCRIPTION
-.I Mkstr
-is used to create files of error messages.
-Its use can make programs with large numbers of error diagnostics much
-smaller, and reduce system overhead in running the program as the
-error messages do not have to be constantly swapped in and out.
-.PP
-.I Mkstr
-will process each of the specified
-.I files,
-placing a massaged version of the input file in a file whose name
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)mkstr.1    6.6 (Berkeley) 5/9/91
+.\"
+.Dd May 9, 1991
+.Dt MKSTR 1
+.Os
+.Sh NAME
+.Nm mkstr
+.Nd create an error message file by massaging C source
+.Sh SYNOPSIS
+.Nm mkstr
+.Op Fl
+.Ar messagefile
+.Ar prefix file ...
+.Sh DESCRIPTION
+.Nm Mkstr
+creates files containing error messages extracted from C source,
+and restructures the same C source, to utilize the created error message
+file.
+The intent of
+.Nm mkstr
+was to reduce the size of large programs and
+reduce swapping (see
+.Sx BUGS
+section below).
+.Pp
+.Nm Mkstr
+processes each of the specified
+.Ar files ,
+placing a restructured version of the input in a file whose name

 consists of the specified
 consists of the specified

-.I prefix 
+.Ar prefix

 and the original name.
 A typical usage of
 and the original name.
 A typical usage of

-.I mkstr
-would be
-.DT
-.PP
-       mkstr pistrings xx *.c
-.PP
-This command would cause all the error messages from the C source
+.Nm mkstr
+is
+.Bd -literal -offset indent
+mkstr pistrings xx *.c
+.Ed
+.Pp
+This command causes all the error messages from the C source

 files in the current directory to be placed in the file
 files in the current directory to be placed in the file

-.I pistrings
-and processed copies of the source for these files to be placed in
+.Ar pistrings
+and restructured copies of the sources to be placed in

 files whose names are prefixed with
 files whose names are prefixed with

-.I xx.
-.PP
-To process the error messages in the source to the message file
-.I mkstr
-keys on the string
-\%`error("'
+.Ar \&xx .
+.Pp
+Options:
+.Bl -tag -width indent
+.It Fl
+Error messages are placed at the end of the specified
+message file for recompiling part of a large
+.Nm mkstr
+ed
+program.
+.El
+.Pp
+.Nm mkstr
+finds error messages in the source by
+searching for the string
+.Li \&`error("'

 in the input stream.
 in the input stream.

-Each time it occurs, the C string starting at the `"' is placed
+Each time it occurs, the C string starting at the
+.Sq \&"\&
+is stored

 in the message file followed by a null character and a new-line character;
 in the message file followed by a null character and a new-line character;

-the null character terminates the message so it can be easily used
-when retrieved, the new-line character makes it possible to sensibly
-.I cat
-the error message file to see its contents.
-The massaged copy of the input file then contains a
-.I lseek
-pointer into the file which can be used to retrieve the message, i.e.:
-.IP
-.DT
-.nf
-\fBchar\fR     efilname[] =  "/usr/lib/pi_strings";
-\fBint\fR      efil = -1;
-.sp
+The new source is restructured with
+.Xr lseek 2
+pointers into the error message file for retrieval.
+.Bd -literal -offset indent
+char efilname = "/usr/lib/pi_strings";
+int efil = -1;
+

 error(a1, a2, a3, a4)
 error(a1, a2, a3, a4)

-{
-       \fBchar\fR buf[256];
+\&{
+       char buf[256];

 
 

-       \fBif\fR (efil < 0) {
+       if (efil < 0) {

                efil = open(efilname, 0);
                efil = open(efilname, 0);

-               \fBif\fR (efil < 0) {
+               if (efil < 0) {

 oops:
                        perror(efilname);
 oops:
                        perror(efilname);

-                       exit(1);
+                       exit 1 ;

                }
        }
                }
        }

-       \fBif\fR (lseek(efil, (long) a1, 0) |\|| read(efil, buf, 256) <= 0)
-               \fBgoto\fR oops;
+       if (lseek(efil, (long) a1, 0) \ read(efil, buf, 256) <= 0)
+               goto oops;

        printf(buf, a2, a3, a4);
 }
        printf(buf, a2, a3, a4);
 }

-.fi
-.PP
-The optional
-.B \-
-causes the error messages to be placed at the end of the specified
-message file for recompiling part of a large
-.IR mkstr \|ed
-program.
-.SH SEE\ ALSO
-lseek(2), xstr(1)
-.SH AUTHORS
-William Joy and Charles Haley
-...SH BUGS
-...All the arguments except the name of the file to be processed could be made unnecessary.
+.Ed
+.Sh SEE ALSO
+.Xr lseek 2 ,
+.Xr xstr 1
+.Sh HISTORY
+.Nm Mkstr
+appeared in
+.Bx 3.0 .
+.Sh BUGS
+.Nm mkstr
+was intended for the limited architecture of the PDP 11 family.
+Very few programs actually use it. The pascal interpreter,
+.Xr \&pi 1
+and the editor,
+.Xr \&ex 1
+are two programs that are built this way.
+It is not an efficient method, the error messages
+should be stored in the program text.