Return to m4.1 CVS log

Up to [Research Unix] / researchv10dc / man / adm / man1

Annotation of researchv10dc/man/adm/man1/m4.1, revision 1.1

1.1     ! root        1: .TH M4 1
        !             2: .CT 1 prog_c
        !             3: .SH NAME
        !             4: m4 \(mi macro processor
        !             5: .SH SYNOPSIS
        !             6: .B m4
        !             7: [
        !             8: .I option ...
        !             9: ]
        !            10: [
        !            11: .I file ...
        !            12: ]
        !            13: .SH DESCRIPTION
        !            14: .I M4\^
        !            15: is a macro processor
        !            16: intended as a front end for C and other languages.
        !            17: Each of the argument files is processed in order;
        !            18: if there are no files, or if a file name is
        !            19: .BR - ,
        !            20: the standard input is read.
        !            21: The processed text is written on the standard output.
        !            22: .PP
        !            23: The options and their effects are as follows:
        !            24: .TP
        !            25: .B -e
        !            26: Operate interactively.
        !            27: Interrupts are ignored and the output is unbuffered.
        !            28: Using this mode requires a special state of mind.
        !            29: .TP
        !            30: .B -s
        !            31: Enable line sync output for the C preprocessor,
        !            32: .RB ( #line " .\|.\|.\|)"
        !            33: .TP
        !            34: .BI -B int\^
        !            35: Change the size of the push-back and argument collection
        !            36: buffers from the default of 4,096.
        !            37: .TP
        !            38: .BI -H int\^
        !            39: Change the size of the symbol table hash array from the
        !            40: default of 199.
        !            41: The size should be prime.
        !            42: .TP
        !            43: .BI -S int\^
        !            44: Change the size of the call stack from the default of 100 slots.
        !            45: Macros take three slots, and non-macro arguments take one.
        !            46: .TP
        !            47: .BI -T int\^
        !            48: Change the size of the token buffer from the default of 512 bytes.
        !            49: .PP
        !            50: The preceding options must appear before any
        !            51: file names or
        !            52: .B -D
        !            53: or
        !            54: .B -U
        !            55: options.
        !            56: .TP
        !            57: \f5-D\fP\f2name\^\fP[\f5=\fP\f2val\^\fP]
        !            58: Defines
        !            59: .I name\^
        !            60: to
        !            61: .I val\^
        !            62: or to null if
        !            63: .I val
        !            64: is missing.
        !            65: .TP
        !            66: .BI -U name\^
        !            67: undefines
        !            68: .IR name .
        !            69: .PP
        !            70: Macro calls
        !            71: have the form:
        !            72: .IP
        !            73: .L name(arg1,arg2, .\|.\|., argn)
        !            74: .PP
        !            75: The
        !            76: .B (
        !            77: must immediately follow the name of the macro.
        !            78: If a defined macro name is not followed by a
        !            79: .BR ( ,
        !            80: it is deemed to have no arguments.
        !            81: Leading unquoted blanks, tabs, and new-lines are ignored while collecting arguments.
        !            82: Potential macro names consist of alphabetic letters,
        !            83: digits, and underscore
        !            84: .BR _ ,
        !            85: where the first character is not a digit.
        !            86: .PP
        !            87: Left and right single quotes are used to quote strings.
        !            88: The value of a quoted string is the string stripped of the quotes.
        !            89: .PP
        !            90: When a macro name is recognized,
        !            91: its arguments are collected by searching for a matching right
        !            92: parenthesis.
        !            93: Macro evaluation proceeds normally during the collection of the arguments,
        !            94: and any commas or right parentheses
        !            95: which happen to turn up within the value of a nested
        !            96: call are as effective as those in the original input text.
        !            97: After argument collection,
        !            98: the value of the macro is pushed back onto the input stream
        !            99: and rescanned.
        !           100: .PP
        !           101: The value of a macro is obtained by replacing
        !           102: each occurrence of
        !           103: .BI $ n\^
        !           104: in the replacement text,
        !           105: where
        !           106: .I n\^
        !           107: is a digit,
        !           108: with the
        !           109: .IR n -th
        !           110: argument.
        !           111: Argument 0 is the name of the macro;
        !           112: missing arguments are replaced by the null string;
        !           113: .B $#
        !           114: is replaced by the number of arguments;
        !           115: .B $*
        !           116: is replaced by a list of all the arguments separated by commas;
        !           117: .B $@
        !           118: is like
        !           119: .BR $* ,
        !           120: but each argument is quoted (with the current quotes).
        !           121: .PP
        !           122: .I M4\^
        !           123: makes available the following built-in macros.
        !           124: They may be redefined, but once this is done the original meaning is lost.
        !           125: Their values are null unless otherwise stated.
        !           126: .TP 12
        !           127: .B define
        !           128: the second argument is installed as the replacement text of the macro
        !           129: whose name is the first argument.
        !           130: .TP
        !           131: .B undefine
        !           132: Remove the definition of the macro named in the argument.
        !           133: .TP
        !           134: .B defn
        !           135: Return the quoted definition of the argument(s);
        !           136: useful for renaming macros, especially built-ins.
        !           137: .TP
        !           138: .B pushdef
        !           139: Like
        !           140: .IR define ,
        !           141: but save any previous definition.
        !           142: .TP
        !           143: .B popdef
        !           144: Remove current definition of the argument(s),
        !           145: exposing the previous one if any.
        !           146: .TP
        !           147: .B ifdef
        !           148: If the first argument is defined, the value is the second argument, otherwise the third.
        !           149: If there is no third argument, the value is null.
        !           150: The word
        !           151: .L unix\^
        !           152: is predefined on
        !           153: .SM UNIX
        !           154: versions of
        !           155: .IR m4 .
        !           156: .TP
        !           157: .B shift
        !           158: Return all but the first argument.
        !           159: The other arguments pushed back with
        !           160: commas in between and quoted to
        !           161: nullify the effect of the extra scan.
        !           162: .TP
        !           163: .B changequote
        !           164: Change quote symbols to the first and second arguments.
        !           165: The symbols may be up to five characters long.
        !           166: .B Changequote\^
        !           167: without arguments restores the original values
        !           168: (i.e., 
        !           169: .LR `\|' ).
        !           170: .TP
        !           171: .B changecom
        !           172: Change left and right comment markers from the default
        !           173: .B #
        !           174: and new-line.
        !           175: With no arguments, the comment mechanism is effectively
        !           176: disabled.
        !           177: With one argument, the left marker becomes the argument and
        !           178: the right marker becomes new-line.
        !           179: With two arguments, both markers are affected.
        !           180: Comment markers may be up to five characters long.
        !           181: .TP
        !           182: .B divert
        !           183: .I m4\^
        !           184: Switch output to one of 10 streams,
        !           185: numbered 0-9 designated by the argument.
        !           186: The final output is the concatenation of the streams
        !           187: in numerical order;
        !           188: stream 0 is the current initially.
        !           189: Output to a stream other than 0 through 9
        !           190: is discarded.
        !           191: .TP
        !           192: .B undivert
        !           193: Cause immediate output of text from diversions named as
        !           194: arguments, or all diversions if no argument.
        !           195: Text may be undiverted into another diversion.
        !           196: Once undiverted, the diverted text is no longer contained in that diversion.
        !           197: .TP
        !           198: .B divnum
        !           199: Return the name of the current output stream.
        !           200: .TP
        !           201: .B dnl
        !           202: reads and discards characters up to and including the next new-line.
        !           203: .TP
        !           204: .B ifelse
        !           205: If the first argument is the same string as the second,
        !           206: then the value is the third argument.
        !           207: If not, and if there are more than four arguments, the process is repeated with arguments 4, 5, 6 and 7.
        !           208: Otherwise, the value is either the fourth string, or, if that is not present,
        !           209: null.
        !           210: .TP
        !           211: .B incr
        !           212: Return the value of the argument incremented by 1.
        !           213: The value of the argument is calculated
        !           214: by interpreting an initial digit-string as a decimal number.
        !           215: .TP
        !           216: .B decr
        !           217: Return the value of the argument decremented by 1.
        !           218: .TP
        !           219: .B eval
        !           220: Evaluate the argument as an arithmetic expression, using 32-bit arithmetic.
        !           221: C-like operators include
        !           222: .BR +-*/% ,
        !           223: bitwise
        !           224: .BR &|^~ ;
        !           225: relationals; parentheses.
        !           226: Octal and hex numbers may be specified as in C.
        !           227: The second argument specifies the radix for the result;
        !           228: the default is 10.
        !           229: The third argument may be used to specify the minimum number
        !           230: of digits in the result.
        !           231: .TP
        !           232: .B len
        !           233: Returns the number of characters in the argument.
        !           234: .TP
        !           235: .B index
        !           236: Return the position in the first argument where the second argument begins (zero origin),
        !           237: or \-1 if the second argument does not occur.
        !           238: .TP
        !           239: .B substr
        !           240: Return a substring of the first argument.
        !           241: The second argument is a zero origin
        !           242: number selecting the first character;
        !           243: the third argument indicates the length of the substring.
        !           244: A missing third argument is taken to be large enough to extend to
        !           245: the end of the first string.
        !           246: .TP
        !           247: .B translit
        !           248: Transliterate the characters in the first argument
        !           249: from the set given by the second argument to the set given by the third,
        !           250: deleting characters that lack a correspondent in the third set.
        !           251: There is no character-range notation.
        !           252: .TP
        !           253: .B include
        !           254: Return the contents of the file named in the argument.
        !           255: .TP
        !           256: .B sinclude
        !           257: Same, but give no diagnostic if the file is inaccessible.
        !           258: .TP
        !           259: .B syscmd
        !           260: Execute the
        !           261: .SM UNIX
        !           262: command given in the first argument.
        !           263: No value is returned.
        !           264: .TP
        !           265: .B sysval
        !           266: The return code from the last call to
        !           267: .IR syscmd .
        !           268: .TP
        !           269: .B maketemp
        !           270: Rill in a string of
        !           271: .LR X
        !           272: characters in the argument with the current process id.
        !           273: .TP
        !           274: .B m4exit
        !           275: Exit immediately from
        !           276: .IR m4 .
        !           277: Argument 1, if given, is the exit code;
        !           278: the default is 0.
        !           279: .TP
        !           280: .B m4wrap
        !           281: Push the argument back at the end of the input.
        !           282: Example:
        !           283: .L m4wrap(`cleanup()')
        !           284: .TP
        !           285: .B errprint
        !           286: Prints the argument
        !           287: on the standard error file.
        !           288: .TP
        !           289: .B dumpdef
        !           290: Print current names and definitions,
        !           291: for the named items, or for all if no arguments are given.
        !           292: .TP
        !           293: .B traceon
        !           294: If there are no arguments, turn on tracing for all macros
        !           295: (including built-ins).
        !           296: Otherwise, turn on tracing for named macros.
        !           297: .TP
        !           298: .B traceoff
        !           299: Turn off trace globally and for any macros specified.
        !           300: Macros specifically traced by
        !           301: .B traceon\^
        !           302: can be untraced only by specific calls to
        !           303: .BR traceoff .
        !           304: .SH EXAMPLES
        !           305: .EX
        !           306: define(fib,`ifelse(define(`n',eval($1))n,0,1,n,1,1,dnl()
        !           307: `eval(fib(n-1)+fib($1-2))')')dnl()
        !           308: fib(2*3)
        !           309: .EE
        !           310: .ns
        !           311: .IP
        !           312: Recursively evaluate a Fibonacci number.
        !           313: The inner
        !           314: .B define
        !           315: avoids some reevaluations.

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