Return to mint.1 CVS log

Up to [Research Unix] / researchv10dc / man / mana

Annotation of researchv10dc/man/mana/mint.1, revision 1.1

1.1     ! root        1: .TH MINT 1  "02 June 1987" "University of Waterloo"
        !             2: .ds ]W "Symbolic Comp. Group
        !             3: .SH NAME
        !             4: mint \- produce usage report from a maple program
        !             5: .SH SYNOPSIS
        !             6: .B mint
        !             7: [
        !             8: .B \-i
        !             9: info_level
        !            10: ]
        !            11: [
        !            12: .B \-l
        !            13: ]
        !            14: [
        !            15: .B \-d
        !            16: library_database
        !            17: ]
        !            18: [
        !            19: .B \-a
        !            20: database_file
        !            21: ]
        !            22: [
        !            23: .B \-q
        !            24: ]
        !            25: [ file ]
        !            26: .SH DESCRIPTION
        !            27: \fIMint\fP produces a report about possible errors in a Maple source file
        !            28: and also reports about how variables are used in the file.
        !            29: If \fIfile\fP is not given, then the standard input file is used to
        !            30: read Maple source statements.
        !            31: Unlike \fImaple\fP, \fImint\fP is not terminated when it reads a
        !            32: quit statement.
        !            33: It is terminated when it reaches the end of file.
        !            34: When started, \fImint\fP normally produces a mint leaf logo.
        !            35: This can be suppressed by the use of the \fB\-q\fP (quiet) option.
        !            36: 
        !            37: The amount of information to be produced by \fImint\fP is specified by the
        !            38: \fIinfo_level\fP argument.
        !            39: The values allowed for this argument are:
        !            40: .nf
        !            41: 
        !            42:         0 \- Display no information.
        !            43:         1 \- Display only severe errors
        !            44:         2 \- Display severe and serious errors
        !            45:         3 \- Display warnings as well as severe and serious errors
        !            46:         4 \- \kxGive a full report on variable usage as well as
        !            47:              \h'|\nxu'displaying errors and warnings
        !            48: 
        !            49: .fi
        !            50: A report for each procedure in the file is displayed
        !            51: separately followed by a global report for statements not contained
        !            52: within any procedure.
        !            53: If the severity of errors found within a procedure is less than
        !            54: what \fIinfo_level\fP specifies, then no report is produced for
        !            55: that procedure.
        !            56: In all cases, the most severe error found in the file will be used
        !            57: to set the exit status for \fImint\fP.
        !            58: Thus, by using an \fIinfo_level\fP of 0, \fImint\fP can be used to
        !            59: determine the severity of errors in a file without actually producing
        !            60: any output at all.
        !            61: If no value is given for \fIinfo_level\fP on the command line, a default
        !            62: value of 2 (severe and serious errors) is used.
        !            63: 
        !            64: The types of errors and warnings found are classified as severe,
        !            65: serious, and warning.  A severe error is an undisputable error.
        !            66: A serious error
        !            67: is almost certainly an error.  However, persons defining procedures
        !            68: for addition to the Maple library may choose to ignore these ``errors''.
        !            69: Warnings are possible errors.
        !            70: They point to constructs that may be correct in some contexts, but
        !            71: probable errors in other contexts.
        !            72: The types of errors and warnings produced are:
        !            73: .in +0.8i
        !            74: .ti -0.8i
        !            75: 
        !            76: \fBSEVERE\fP
        !            77: 
        !            78: .ti -0.4i
        !            79: Syntax errors
        !            80: .br
        !            81: A caret symbol will point to the token
        !            82: that is being read when the error occurred.
        !            83: 
        !            84: .ti -0.4i
        !            85: Duplicated parameter
        !            86: .br
        !            87: A name appears more than once in a parameter list for a
        !            88: procedure.
        !            89: 
        !            90: .ti -0.4i
        !            91: Duplicated local
        !            92: .br
        !            93: A name is declared more than once in the list of local
        !            94: variables for a procedure.
        !            95: 
        !            96: .ti -0.4i
        !            97: Local variable and parameter conflict
        !            98: .br
        !            99: A name is used both as a parameter and a local
        !           100: variable within a procedure.  In further analysis,
        !           101: the name is treated as a parameter.
        !           102: 
        !           103: .ti -0.4i
        !           104: Local variable and system-defined name conflict
        !           105: .br
        !           106: The name of a local variable is also used by Maple as a
        !           107: system-defined name.
        !           108: 
        !           109: .ti -0.4i
        !           110: Parameter and system-defined name conflict
        !           111: .br
        !           112: The name of a parameter is also used by Maple as a
        !           113: system-defined name.
        !           114: 
        !           115: .ti -0.4i
        !           116: Duplicated loop name
        !           117: .br
        !           118: A loop nested within another loop uses as its loop
        !           119: control variable the same name that the outer loop uses.
        !           120: 
        !           121: .ti -0.4i
        !           122: Break or next statement outside of a loop
        !           123: .br
        !           124: A break or a next statement occurs outside of any loop.
        !           125: (Break or next may still be used as names within an
        !           126: expression outside of a loop.)
        !           127: 
        !           128: .ti -0.4i
        !           129: RETURN or ERROR function call outside of a procedure
        !           130: .br
        !           131: A function call to RETURN or ERROR occurs outside of
        !           132: a procedure body.  (RETURN or ERROR may still be used
        !           133: as names if they are not invoked as functions.)
        !           134: 
        !           135: .ti -0.4i
        !           136: Unreachable code
        !           137: .br
        !           138: There are statements which follow directly after a goto type
        !           139: of statement.  These statements are unreachable and will never
        !           140: be executed.  A goto statement is a next statement, a break
        !           141: statement, a quit, stop, or done statement, a RETURN() call,
        !           142: an ERROR() call.
        !           143: An if statement all branches of which end in a goto statement
        !           144: is also considered a goto statement.
        !           145: 
        !           146: .ti -0.8i
        !           147: \fBSERIOUS\fP
        !           148: 
        !           149: .ti -0.4i
        !           150: Overly long name
        !           151: .br
        !           152: A name whose length is too long is used.  The length of
        !           153: the name is truncated to the maximum allowed.
        !           154: 
        !           155: .ti -0.4i
        !           156: Unused local variable
        !           157: .br
        !           158: A local variable is declared for a procedure but never
        !           159: used within the procedure body.
        !           160: 
        !           161: .ti -0.4i
        !           162: Local variable assigned a value but not used otherwise
        !           163: .br
        !           164: A local variable is assigned a value within a procedure but
        !           165: is not otherwise used.
        !           166: 
        !           167: .ti -0.4i
        !           168: Local variable never assigned a value but used as a value
        !           169: .br
        !           170: A local variable was never assigned a value in a procedure but
        !           171: within the procedure its value is used in an expression.
        !           172: Such an expression would contain a pointer to a non-existent
        !           173: local variable if the expression were returned or assigned to
        !           174: a global variable.
        !           175: 
        !           176: .ti -0.4i
        !           177: System-defined name is overwritten
        !           178: .br
        !           179: A name which is treated as a system-defined name by Maple
        !           180: is assigned a value.
        !           181: The class of system-defined names includes names which are
        !           182: special names for the Maple kernel, e.g., true and Digits,
        !           183: names of built-in functions, e.g., anames and lprint,
        !           184: names of functions which are automatically readlib-defined, e.g.,
        !           185: cat or help.
        !           186: Also included are names that are special to routines for evalf,
        !           187: diff, expand, etc.
        !           188: Examples of these are Pi and sinh.
        !           189: These special names generally should not be assigned a value in order
        !           190: for some library routines to work properly.
        !           191: Included in the report is an indication of which parts of Maple use
        !           192: the system-defined names.
        !           193: 
        !           194: .ti -0.4i
        !           195: Dubious global name in a procedure
        !           196: .br
        !           197: A global name is used within a procedure.  A global name is
        !           198: a name which is not a parameter, a local name, a system-defined name, or
        !           199: a catenated name.
        !           200: A quoted name used as an argument to the routines lprint, print, and
        !           201: ERROR is probably used just for output and is not considered a name.
        !           202: Global names used as procedure
        !           203: names in a function call are not considered errors.
        !           204: Also excluded are names of files in the Maple library, e.g.,
        !           205: `convert/ratpoly`.
        !           206: All remaining names are considered as global names.
        !           207: By convention, global names used in a package of routines should
        !           208: begin with the `_` (underscore) character.
        !           209: Those that do not are considered dubious and are reported here.
        !           210: 
        !           211: .ti -0.4i
        !           212: Library file name overwritten
        !           213: .br
        !           214: The name of a library file, e.g., `convert/ratpoly`, is assigned
        !           215: a value.  It is usual for the name of a library file to also be
        !           216: the name of a library function.  Hence, the library function
        !           217: `convert/ratpoly` is no longer accessible.
        !           218: (The \fB\-l\fP (library file) option will downgrade these messages
        !           219: from a serious error to a report.)
        !           220: 
        !           221: .ti -0.4i
        !           222: Unused parameter in a procedure
        !           223: .br
        !           224: A name specified in the parameter list of a procedure is
        !           225: never used in the procedure.  This is considered a serious
        !           226: error if `args' is  never used in the procedure either.
        !           227: If args is used in the procedure, then it's possible that
        !           228: the parameter may be accessed through a construct using `arg'
        !           229: and this error is downgraded to a warning.
        !           230: 
        !           231: .ti -0.4i
        !           232: Wrong argument count in a procedure call
        !           233: .br
        !           234: The number of arguments passed in a procedure call doesn't match the
        !           235: number of formal arguments in the definition of a procedure of the
        !           236: same name recorded in the library database file.
        !           237: A library database file (cf. \fBDATABASE FILES\fP) contains information
        !           238: about the minimum number of arguments expected for a procedure, the
        !           239: maximum number of arguments, whether `nargs' is used in the procedure
        !           240: body, and the name of the file in which the procedure is defined.
        !           241: If the number of actual arguments passed is either less than the
        !           242: minimum arguments expected or more than the maximum number expected
        !           243: \fIand\fP `nargs' is not used in the procedure body, then a warning is
        !           244: generated.
        !           245: This warning is suppressed if one of the arguments passed is `args'.
        !           246: It is a common practice for a procedure to take its argument list,
        !           247: contained in the expression sequence `args', and pass that on to
        !           248: other procedures.
        !           249: What appears to \fImint\fP as one argument is in reality a sequence
        !           250: of arguments.
        !           251: .ti -0.8i
        !           252: 
        !           253: \fBWARNING\fP
        !           254: 
        !           255: .ti -0.4i
        !           256: Equation used as a statement
        !           257: .br
        !           258: This may be intentional.  On the other hand, it's common
        !           259: for many Fortran and C programmers to mistype '=' for
        !           260: the assignment operator which is ':=' in Maple.
        !           261: 
        !           262: .ti -0.4i
        !           263: Unused parameter in a procedure
        !           264: .br
        !           265: See similar entry under serious errors.
        !           266: 
        !           267: .ti -0.4i
        !           268: Global name used
        !           269: .br
        !           270: A global name which may or may not start with '_' is used within
        !           271: this procedure.
        !           272: 
        !           273: .ti -0.4i
        !           274: Catenated name used
        !           275: .br
        !           276: A name is formed through the catenation operator.
        !           277: 
        !           278: .in -0.8i
        !           279: \fBOTHER REPORTS\fP
        !           280: .sp
        !           281: If \fIinfo_level\fP is 4, then a usage report is given for each procedure
        !           282: as well as global statements within the file.
        !           283: Each usage report shows how parameters, local variables, global variables,
        !           284: system-defined names and catenated names are used.
        !           285: As well can easily be done, the following information about how a
        !           286: variable is used may be provided:
        !           287: .nf
        !           288: 
        !           289:     1.  Used as a value
        !           290:     2.  Used as a table or list element
        !           291:     3.  Used as a call-by-value parameter
        !           292:     4.  Used as a call-by-name parameter (a quoted parameter)
        !           293:     5.  Called as a function
        !           294:     6.  Assigned a procedure
        !           295:     7.  Assigned a list
        !           296:     8.  Assigned a set
        !           297:     9.  Assigned a range
        !           298:     10. Assigned a value as a table or list element
        !           299:     11. \kxAssigned a function value
        !           300:         \h'|\nxu'(assigned a value to remember as a function value)
        !           301: 
        !           302: .fi
        !           303: 
        !           304: In addition, a list of all the error messages generated is given.
        !           305: 
        !           306: .SH COMMAND OPTIONS
        !           307: The \fB\-i\fP (info level) and \fB\-q\fP (quiet) options are explained
        !           308: above.
        !           309: The \fB\-l\fP (library file) option will suppress the catenated name
        !           310: warning and the global name warning if only one of each is used
        !           311: outside of any procedure.
        !           312: Typically, a Maple library source file will contain one of each for
        !           313: use in loading the library file.
        !           314: This option will also suppress error messages about library file names
        !           315: being overwritten since one of the purposes of a library file is to
        !           316: assign a procedure to a library file name.
        !           317: Moreover, warnings about the assignment of values to the system-defined
        !           318: names Digits and printlevel are suppressed since this often happens
        !           319: in a library file.
        !           320: 
        !           321: .SH INITIALIZATION FILE
        !           322: If there is a file named .mintrc in your home directory, \fImint\fP
        !           323: will read this file for command line options.
        !           324: This file may contain several lines containing command line options or
        !           325: arguments as you would type them on a command line.
        !           326: Since \fImint\fP reads this file and then scans the actual command line,
        !           327: arguments on the actual command line can override arguments in the
        !           328: initialization file.
        !           329: A good use of the initialization file may be to enter the name of the
        !           330: Maple library procedure database file when using the \fB\-d\fP option,
        !           331: obviating the need to type this each time \fImint\fP is used.
        !           332: 
        !           333: .SH PROCEDURE DATABASE FILES
        !           334: A procedure database file contains information about the definition of
        !           335: procedures which is useful in ensuring that these procedures are
        !           336: used correctly.
        !           337: Each line in a database file contains the following:
        !           338: 
        !           339: .nf
        !           340:         <name> <min\ args> <max\ args> <nargs\ used> <file\ name>
        !           341: .fi
        !           342: 
        !           343: where <name> is a legal Maple name without any embedded blanks,
        !           344: <min\ args> is the minimum number of arguments expected for
        !           345: <name>, <max\ args> is the maximum number of arguments, <nargs\ used>
        !           346: is 1 if `nargs' is used in the procedure body for <name> and
        !           347: 0 otherwise, <file\ name> is the name of the file in which <name>
        !           348: is defined.
        !           349: The entries on each line are in free format but must be separated
        !           350: from one another by at least one space character.
        !           351: The values for <min\ args> and <max\ args> should be numbers in
        !           352: the range 0 to 999.
        !           353: If <max\ args> is 999 for an entry, that denotes that the procedure
        !           354: has no upper limit on the number of arguments.
        !           355: There may be multiple entries for a particular procedure.
        !           356: Later entries supercede earlier ones.
        !           357: 
        !           358: A procedure database file for the entire Maple library is generated
        !           359: or updated periodically.
        !           360: This file is
        !           361: /usr/maple/data/mint.db and contains close to 1200 entries and
        !           362: it takes \fImint\fP about 7 seconds to read this file.
        !           363: 
        !           364: A private database file can be generated through the use of
        !           365: the \fB\-a\fP command line option for \fImint\fP.
        !           366: A file name must follow \fB\-a\fP on the command line and is taken
        !           367: to be a procedure database file.
        !           368: As \fImint\fP scans procedure definitions in the input file, it
        !           369: will append procedure database entries into the database file.
        !           370: For information gathered automatically by \fImint\fP about a
        !           371: procedure, <min\ args> and <max\ args> will both be the number of
        !           372: formal arguments used in the procedure definition.
        !           373: You can edit the database file to adjust these values.
        !           374: Remember that use of `nargs' in a procedure body sets the <nargs seen>
        !           375: field to 1 in the database entry and that this will turn off
        !           376: argument count checking for that procedure.
        !           377: 
        !           378: .SH EXAMPLES
        !           379: 
        !           380: .ft CW
        !           381: .nf
        !           382: mint -d /usr/maple/data/mint.db -a my.db -i 4  rat_poisson
        !           383: mint -d /usr/maple/data/mint.db -d my.db       rat_trap
        !           384: mint -i 1 -q                                   warfarin
        !           385: .fi
        !           386: .ft P
        !           387: 
        !           388: The first example gives a full report (info_level = 4) for the
        !           389: Maple source file rat_poisson.
        !           390: It reads the Maple library database file and uses this to check that
        !           391: procedures defined in the Maple library are called with the correct
        !           392: number of arguments.
        !           393: Information about procedures defined in rat_poisson is \fIappended\fP
        !           394: to my.db.
        !           395: 
        !           396: In the second example, both the Maple library database file and
        !           397: the private database file my.db are used to check number of arguments
        !           398: used in procedure calls in the file rat_trap.
        !           399: Entries in my.db supercede entries in the library database file
        !           400: if the name of a library procedure has been redefined in my.db.
        !           401: 
        !           402: In the third example, no argument count checking is done.
        !           403: Since the info_level is set to 1, only severe errors are
        !           404: reported.
        !           405: Since the \fB\-q\fP  (quiet) option is used, the printing
        !           406: of the \fImint\fP leaf logo is suppressed in the output.
        !           407: 
        !           408: .SH FILES USED
        !           409: \&.mintrc               \- Mint initialization file
        !           410: /usr/maple/data/mint.db \- \kxMaple library procedure database
        !           411: \h'|\nxu'(The location of the database may be different for each site)
        !           412: .SH SEE ALSO
        !           413: maple
        !           414: 
        !           415: .SH STATUS
        !           416: \fIMint\fP will return an exit status of 1, 2, or 3 if the
        !           417: worst error it detects is a warning, serious error, or severe
        !           418: error, respectively.  An exit status of 0 is returned if no
        !           419: errors or warnings are found.
        !           420: 

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