Return to error.1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / pgrm / error

Annotation of 43BSDReno/pgrm/error/error.1, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1980, 1990 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted provided
        !             5: .\" that: (1) source distributions retain this entire copyright notice and
        !             6: .\" comment, and (2) distributions including binaries display the following
        !             7: .\" acknowledgement:  ``This product includes software developed by the
        !             8: .\" University of California, Berkeley and its contributors'' in the
        !             9: .\" documentation or other materials provided with the distribution and in
        !            10: .\" all advertising materials mentioning features or use of this software.
        !            11: .\" Neither the name of the University nor the names of its contributors may
        !            12: .\" be used to endorse or promote products derived from this software without
        !            13: .\" specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"     @(#)error.1    6.5 (Berkeley) 7/24/90
        !            19: .\"
        !            20: .Dd July 24, 1990
        !            21: .Dt ERROR 1
        !            22: .Os BSD 4
        !            23: .Sh NAME
        !            24: .Nm error
        !            25: .Nd analyze and disperse compiler error messages
        !            26: .Sh SYNOPSIS
        !            27: .Nm error
        !            28: .Op Fl n
        !            29: .Op Fl s
        !            30: .Op Fl q
        !            31: .Op Fl v
        !            32: .Op Fl t Ar suffixlist
        !            33: .Op Fl I Ar ignorefile
        !            34: .Op name
        !            35: .Sh DESCRIPTION
        !            36: .Nm Error
        !            37: analyzes and optionally disperses the diagnostic error messages
        !            38: produced by a number of compilers and language processors to the source
        !            39: file and line where the errors occurred.  It can replace the painful,
        !            40: traditional methods of scribbling abbreviations of errors on paper, and
        !            41: permits error messages and source code to be viewed simultaneously
        !            42: without machinations of multiple windows in a screen editor.
        !            43: .Pp
        !            44: Options are:
        !            45: .Tw Ds
        !            46: .Tp Fl n
        !            47: Do
        !            48: .Em not
        !            49: touch any files; all error messages are sent to the
        !            50: standard output.
        !            51: .Tp Fl q
        !            52: The user is
        !            53: .Ar queried
        !            54: whether s/he wants to touch the file.
        !            55: A ``y'' or ``n'' to the question is necessary to continue.
        !            56: Absence of the
        !            57: .Fl q
        !            58: option implies that all referenced files
        !            59: (except those referring to discarded error messages)
        !            60: are to be touched.
        !            61: .Tp Fl v
        !            62: After all files have been touched,
        !            63: overlay the visual editor
        !            64: .Xr vi 1
        !            65: with it set up to edit all files touched,
        !            66: and positioned in the first touched file at the first error.
        !            67: If
        !            68: .Xr vi 1
        !            69: can't be found, try
        !            70: .Xr ex 1
        !            71: or
        !            72: .Xr ed 1
        !            73: from standard places.
        !            74: .Tp Fl t
        !            75: Take the following argument as a suffix list.
        !            76: Files whose suffixes do not appear in the suffix list are not touched.
        !            77: The suffix list is dot separated, and ``*'' wildcards work.
        !            78: Thus the suffix list:
        !            79: .Pp
        !            80: .Dl ".c.y.foo*.h"
        !            81: .Pp
        !            82: allows
        !            83: .Nm error
        !            84: to touch files ending with ``.c'', ``.y'', ``.foo*'' and ``.y''.
        !            85: .Tp Fl s
        !            86: Print out
        !            87: .Em statistics
        !            88: regarding the error categorization.
        !            89: Not too useful.
        !            90: .Tp
        !            91: .Pp
        !            92: .Nm Error
        !            93: looks at the error messages,
        !            94: either from the specified file
        !            95: .Ar name
        !            96: or from the standard input,
        !            97: and attempts to determine which
        !            98: language processor produced each error message,
        !            99: determines the source file and line number to which the error message refers,
        !           100: determines if the error message is to be ignored or not,
        !           101: and inserts the (possibly slightly modified) error message into
        !           102: the source file as a comment on the line preceding to which the
        !           103: line the error message refers.
        !           104: Error messages which can't be categorized by language processor
        !           105: or content are not inserted into any file,
        !           106: but are sent to the standard output.
        !           107: .Nm Error
        !           108: touches source files only after all input has been read.
        !           109: .Pp
        !           110: .Nm Error
        !           111: is intended to be run
        !           112: with its standard input
        !           113: connected via a pipe to the error message source.
        !           114: Some language processors put error messages on their standard error file;
        !           115: others put their messages on the standard output.
        !           116: Hence, both error sources should be piped together into
        !           117: .Nm error .
        !           118: For example, when using the
        !           119: .Xr csh 1
        !           120: syntax,
        !           121: .Pp
        !           122: .Dl make \-s lint \&| error \-q \-v
        !           123: .Pp
        !           124: will analyze all the error messages produced
        !           125: by whatever programs
        !           126: .Xr make 1
        !           127: runs when making lint.
        !           128: .Pp
        !           129: .Nm Error
        !           130: knows about the error messages produced by:
        !           131: .Xr make 1 ,
        !           132: .Xr cc 1 ,
        !           133: .Xr cpp 1 ,
        !           134: .Xr ccom 1 ,
        !           135: .Xr as 1 ,
        !           136: .Xr ld 1 ,
        !           137: .Xr lint 1 ,
        !           138: .Xr pi 1 ,
        !           139: .Xr pc 1 ,
        !           140: .Xr f77 1 ,
        !           141: and
        !           142: .Em DEC Western Research Modula\-2 .
        !           143: .Nm Error
        !           144: knows a standard format for error messages produced by
        !           145: the language processors,
        !           146: so is sensitive to changes in these formats.
        !           147: For all languages except
        !           148: .Em Pascal ,
        !           149: error messages are restricted to be on one line.
        !           150: Some error messages refer to more than one line in more than
        !           151: one files;
        !           152: .Nm error
        !           153: will duplicate the error message and insert it at
        !           154: all of the places referenced.
        !           155: .Pp
        !           156: .Nm Error
        !           157: will do one of six things with error messages.
        !           158: .Tp Em synchronize
        !           159: Some language processors produce short errors describing
        !           160: which file it is processing.
        !           161: .Nm Error
        !           162: uses these to determine the file name for languages that
        !           163: don't include the file name in each error message.
        !           164: These synchronization messages are consumed entirely by
        !           165: .Nm error .
        !           166: .Tp Em discard
        !           167: Error messages from
        !           168: .Xr lint 1
        !           169: that refer to one of the two
        !           170: .Xr lint 1
        !           171: libraries,
        !           172: .Pa /usr/libdata/lint/llib-lc
        !           173: and
        !           174: .Pa /usr/libdata/lint/llib-port
        !           175: are discarded,
        !           176: to prevent accidently touching these libraries.
        !           177: Again, these error messages are consumed entirely by
        !           178: .Nm error .
        !           179: .Tp Em nullify
        !           180: Error messages from
        !           181: .Xr lint 1
        !           182: can be nullified if they refer to a specific function,
        !           183: which is known to generate diagnostics which are not interesting.
        !           184: Nullified error messages are not inserted into the source file,
        !           185: but are written to the standard output.
        !           186: The names of functions to ignore are taken from
        !           187: either the file named
        !           188: .Pa .errorrc
        !           189: in the users's home directory,
        !           190: or from the file named by the
        !           191: .Fl I
        !           192: option.
        !           193: If the file does not exist,
        !           194: no error messages are nullified.
        !           195: If the file does exist, there must be one function
        !           196: name per line.
        !           197: .Tp Em not file specific
        !           198: Error messages that can't be intuited are grouped together,
        !           199: and written to the standard output before any files are touched.
        !           200: They will not be inserted into any source file.
        !           201: .Tp Em file specific
        !           202: Error message that refer to a specific file,
        !           203: but to no specific line,
        !           204: are written to the standard output when
        !           205: that file is touched.
        !           206: .Tp Em true errors
        !           207: Error messages that can be intuited are candidates for
        !           208: insertion into the file to which they refer.
        !           209: .Tp
        !           210: .Pp
        !           211: Only true error messages are candidates for inserting into
        !           212: the file they refer to.
        !           213: Other error messages are consumed entirely by
        !           214: .Nm error
        !           215: or are written to the standard output.
        !           216: .Nm Error
        !           217: inserts the error messages into the source file on the line
        !           218: preceding the line the language processor found in error.
        !           219: Each error message is turned into a one line comment for the
        !           220: language,
        !           221: and is internally flagged
        !           222: with the string ``###'' at
        !           223: the beginning of the error,
        !           224: and ``%%%'' at the end of the error.
        !           225: This makes pattern searching for errors easier with an editor,
        !           226: and allows the messages to be easily removed.
        !           227: In addition, each error message contains the source line number
        !           228: for the line the message refers to.
        !           229: A reasonably formatted source program can be recompiled
        !           230: with the error messages still in it,
        !           231: without having the error messages themselves cause future errors.
        !           232: For poorly formatted source programs in free format languages,
        !           233: such as C or Pascal,
        !           234: it is possible to insert a comment into another comment,
        !           235: which can wreak havoc with a future compilation.
        !           236: To avoid this, programs with comments and source
        !           237: on the same line should be formatted
        !           238: so that language statements appear before comments.
        !           239: .Pp
        !           240: .Nm Error
        !           241: catches interrupt and terminate signals,
        !           242: and if in the insertion phase,
        !           243: will orderly terminate what it is doing.
        !           244: .Sh FILES
        !           245: .Dw ~/.errorrc
        !           246: .Di L
        !           247: .Dp Pa ~/.errorrc
        !           248: function names to ignore for
        !           249: .Xr lint 1
        !           250: error messages
        !           251: .Dp Pa /dev/tty
        !           252: user's teletype
        !           253: .Dp
        !           254: .Sh HISTORY
        !           255: .Nm Error
        !           256: appeared in 4.0 BSD.
        !           257: .Sh AUTHOR
        !           258: Robert Henry
        !           259: .Sh BUGS
        !           260: .Pp
        !           261: Opens the teletype directly to do user querying.
        !           262: .Pp
        !           263: Source files with links make a new copy of the file with
        !           264: only one link to it.
        !           265: .Pp
        !           266: Changing a language processor's format of error messages
        !           267: may cause
        !           268: .Nm error
        !           269: to not understand the error message.
        !           270: .Pp
        !           271: .Nm Error ,
        !           272: since it is purely mechanical,
        !           273: will not filter out subsequent errors caused by `floodgating'
        !           274: initiated by one syntactically trivial error.
        !           275: Humans are still much better at discarding these related errors.
        !           276: .Pp
        !           277: Pascal error messages belong after the lines affected
        !           278: (error puts them before).  The alignment of the `\\' marking
        !           279: the point of error is also disturbed by
        !           280: .Nm error .
        !           281: .Pp
        !           282: .Nm Error
        !           283: was designed for work on CRT's at reasonably high speed.
        !           284: It is less pleasant on slow speed terminals, and has never been
        !           285: used on hardcopy terminals.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.