From a0f7cb2db4c51a4a0fed37fde7f1992aec0cc9bb Mon Sep 17 00:00:00 2001 From: Greg McGary Date: Fri, 18 Apr 1997 06:32:28 +0000 Subject: Initial revision --- mkid.1 | 187 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 mkid.1 (limited to 'mkid.1') diff --git a/mkid.1 b/mkid.1 new file mode 100644 index 0000000..6cdf1a7 --- /dev/null +++ b/mkid.1 @@ -0,0 +1,187 @@ +.TH MKID 1 +.SH NAME +mkid \- make an id database +.SH SYNOPSIS +.B mkid +.RB [ \-v ] +.RB [ \-f \^out-file] +.RB [ \-s \^directory] +.RB [ \-r \^directory] +.RB [ \-S \^scanarg] +.RB [ \-a \^arg-file] +.RB [ \- ] +.RB [ \-u ] +.RB [ files... ] +.SH DESCRIPTION +.I Mkid\^ +builds a database that stores numbers and identifier names, as well +as the names of the files in which they occur. +.I Mkid\^ +is particularly useful with large programs spread out across multiple +source files. It serves as an aid for program maintenance and as a +.I guide\^ +for perusing a program. +.PP +The following options are recognized: +.TP 10 +.B \-v +Verbose. +Report +.IR mkid 's +progress in building the database. The output comes on standard error. +.TP 10 +.BI \-f out-file\^ +Write the finished database into +.IR out-file . +.B ID\^ +is the default. +Normally the names of the files scanned are written to the database +as specified in the argument list. If the database sepcified with +.B \-f +is not located in the current directory, then the file names are +adjusted so that they are relative to the directory that the +database is located in. +.TP 10 +.BI \-s directory\^ +.TP 10 +.BI \-r directory\^ +If +.IR mkid 's +attempt to open a source-file fails, it will try to checkout the +corresponding SCCS or RCS file if present. The +.B \-s +option tells +.I mkid\^ +which directory holds the SCCS file. +Similarly, the +.B \-r +option tells +.I mkid\^ +which directory holds the RCS file. +If neither the RCS or SCCS directories are specified, +.I mkid\^ +will first look for an SCCS file in the current directory, then in +.BI sccs , +and finally in +.BI SCCS . +It will then look for an RCS file in the current directory, and finally in +.BI RCS . +.TP 10 +.BI \-a arg-file\^ +Open and read +.I arg-file\^ +in order to obtain a list of source file arguments. Source file names +must appear one to a line. +.BI \-S , +.BI \-r , +and +.BI \-s +arguments may also be placed one per line in +.IR file . +They are distinguished from source file names by their leading `-'. If a file name begins +with `-', it can be distinguished from an argument by explicitly prepending the current +directory string: `./'. +.TP 10 +.B \- +This operates in the same manner as the +.B \-a +option described above, but reads from the standard input instead of a file. +.TP 10 +.B \-u +Update an existing database. Only those files that have been modified +since the database was built will be rescanned. This is a significant +time-saver for updating large databases where few sources have changed. +.TP 10 +.B files... +If neither the +.BI \-a , +.BI \- , +nor +.BI \-u , +arguments have been specified, take file names from the command line. +.TP 10 +.BI \-S scanarg\^ +.I Mkid\^ +scans source files in order to obtain numbers and identifier names. +Since the lexical rules of languages differ, +.I mkid\^ +applies a different scanning function to each language in order +to conform to that language's lexical rules. +.I Mkid\^ +determines the source file's language by examining its filename +suffix which commonly occurs after a dot (`.'). +The +.B \-S +argument is a way of passing language specific arguments to the +scanner for that language. This argument takes a number of forms: +.br +-S= +.br +-S- +.br ++S- +.br +-S// +.br +The first form associates a suffix with a language. +For example -S.c=vhil would cause all .c files to be scanned +as though they were language vhil rather than c. +You may find +out which suffixes are defined for which languages with the following +options: `-S=?' tells which language is bound to +.IR , +`-S?=' tells which suffixes are bound to +.IR , +and `-S?=?' reports all bindings between suffixes and languages. +.PP +The second form passes an argument for processing by the scanner +for a specific language. The third form passes an argument to +all scanners. +.PP +Finally, the // form defines a shell command +to filter the file with. This can be used to run an arbitrary +program to filter the contents of a file before it is passed +to one of the existing language scanners. It is typically +used in conjunction with the plain text scanner. +The first defines a new language, the second +specifies an existing language whose scanner will be used, +and the remaining is an arbitrary shell command. +.PP +You may get a brief summary of the scanner-specific options for a +language by supplying the following option: `-S?'. +.PP +Here is a brief summary of the options for the +.I `asm'\^ +(assembler) language. +.PP +The +.B \-u\^ +option controls whether or not the assembler scanner should strip +off a leading +.I underscore\^ +(`_') character. If your assembler prepends an +.I underscore\^ +to external symbols, then you should tell the scanner to strip it +off, so that references to the same symbol from assembly and from +a high-level language will look the same. +.PP +The +.B \-c\^ +option supplies the character(s) used to begin a comment that extends +to the end of the line. +.PP +The +.B \-a\^ +option indicates character(s) that are legal in names, in addition to +the alpha-numeric characters. If the option appears as `-a', names +that contain these characters are ignored. If it appears as `+a', these +names are added to the database. +.SH BUGS +This manual page needs to be more complete about the scanner-specific +arguments. +.PP +At the moment, the only scanners implemented are for C, assembly +language, and plain text. There ought to be scanners for Ada, Pascal, +Fortran, and Lisp. +.SH SEE ALSO +lid(1), deroff(1), detex(1). -- cgit v1.2.3