diff options
Diffstat (limited to 'man/1/m4')
| -rw-r--r-- | man/1/m4 | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/man/1/m4 b/man/1/m4 new file mode 100644 index 00000000..f90ad959 --- /dev/null +++ b/man/1/m4 @@ -0,0 +1,233 @@ +.TH M4 1 +.SH NAME +m4 \- macro processor +.SH SYNOPSIS +.B m4 +[ +.BI -D name = value +] [ +.BI -U name +] [ +.I file +\&... +] +.SH DESCRIPTION +.I M4 +is a general-purpose macro processor. +It copies text from each of the input +.I files +in order (or standard input by default), and writes the processed text to the standard output. +.PP +Macro calls +have the form +.IP +.IB name ( arg1,\ arg2,\ ...,\ argn ) +.PP +The `(' must immediately follow the name of the macro. +If a defined macro name is not followed by a `(', +it is deemed to have no arguments. +Leading unquoted blanks, tabs, and newlines are ignored while collecting arguments. +A comma within a nested parenthesis is part of an argument value, not an argument separator. +Potential macro names consist of alphabetic letters, Unicode characters, +digits, and underscore `\_', where the first character is not a digit. +.PP +The left and right single quotes(ie, grave and acute accents \`\|\' ) are used to quote strings. +Because the left and right quotes are distinct, quoted strings may nest. +The value of a quoted string is the string stripped of the outermost quotes. +.PP +When +.I m4 +recognises a macro name, followed by a `(', it collects arguments up to a matching right parenthesis. +Macro evaluation proceeds normally during this collection, and the text produced by those macro calls +is interpreted exactly as if it had been in the original input stream (in place of the corresponding macro call). +Thus, any commas or right parentheses within the value of a nested +call are as effective as those in the original input text. +(Remember however that commas within +.I nested +parentheses are not argument separators.) +After argument collection, +the value of the macro is pushed back onto the input stream +and rescanned. +.PP +.I M4 +makes available the following built-in macros. +They may be redefined, but once this is done the original meaning is lost. +Their values are null unless otherwise stated. +.TF changequote +.TP +changecom +Change the starting and ending delimiters for subsequent comments to the first and second arguments. +If the second argument is missing or an empty string, comments will be ended by newline. +If there are no arguments, there are no comments. +.TP +changequote +Change quote characters to the first and second arguments. +.I Changequote +without arguments restores the original values of +.BR `\|' . +.TP +define +The second argument is installed as the value of the macro +whose name is the first argument. +When the macro is later called (expanded), +each occurrence in the replacement text of +.BI $ n, +where +.I n +is a digit, +is replaced by the +.IR n -th +argument of that macro call. +Argument 0 is the name of the macro; +missing arguments are replaced by the null string. +If the macro value is the same as its name, or the value is simply +.BR $0 , +the result is the macro name. +.TP +divert +.I M4 +maintains 10 output streams, +numbered 0-9. +The final output is the concatenation of the streams +in numerical order; +initially stream 0 is the current stream. +The +.I divert +macro changes the current output stream to its (digit-string) +argument. +Output diverted to a stream other than 0 through 9 +is discarded. +.TP +divnum +Returns the value of the current output stream. +.TP +dnl +Reads and discards characters up to and including the next newline. +.TP +dumpdef +Prints current names and definitions, +for the named items, or for all if no arguments are given. +.TP +errprint +Prints its argument +on the diagnostic output file. +.TP +eval +Evaluates its argument as an arithmetic expression, using 32-bit arithmetic. +Operators are those of Limbo: the binary operators +.BR || , +.BR && , +.BR | , +.BR ^ , +.BR & , +.BR "== !=" , +.BR "< > >= <=" , +.B "<< >>" +(arithmetic shifts), +.BR "+ -" , +.BR "* / %" , +.BR "**" " (power)"; +the unary operators +.BR + , +.BR - , +.BR ~ , +.BR ! ; +and parenthesis. +The operator precedence is the same as in Limbo. +Right shifts are signed. +.TP +ifdef +If the first argument is defined, the value is the second argument, otherwise the third. +If there is no third argument, the value is null. +The word +.B inferno +is predefined with +.RB ` inferno ' +as its replacement text. +.TP +ifelse +Has three or more arguments. +If the first argument is the same string as the second, +then the value is the third argument. +If not, the process is repeated with arguments 4, 5, 6 and so on, in groups of three. +If no match is found, the result is the remaining argument (not part of a group of three), +or null if none is present. +.TP +include +Returns the contents of the file named in the argument. +.TP +incr +Returns the value of its argument incremented by 1. +The value of the argument is calculated +by interpreting an initial digit-string as a decimal number. +.TP +index +Returns the position in its first argument where the second argument begins (zero origin), +or \-1 if the second argument does not occur. +.TP +len +Returns the number of characters in its argument. +.TP +maketemp +Returns its first argument after replacing any trailing XXXs by the current host name, process ID, and a unique letter. +Normally used to create unique temporary file names. +.TP +sinclude +The same as +.I include, +except that it +says nothing if the file is inaccessible. +.TP +substr +Returns a substring of its first argument. +The second argument is a zero origin +number selecting the first character; +the third argument indicates the length of the substring. +A missing third argument is taken to be large enough to extend to +the end of the first string. +\" .TP +\" syscmd +\" executes the shell command given in the first argument. +\" No value is returned. +.TP +translit +Transliterates the characters in its first argument +from the set given by the second argument to the set given by the third. +No abbreviations are permitted. +.TP +undefine +Removes the definition of the macro named in its argument. +.TP +undivert +Causes immediate output of text from diversions named as +arguments, or all diversions if no argument. +Text may be undiverted into another diversion. +Undiverting discards the diverted text. +.PD +.PP +.I M4 +interprets the +.B -D +and +.B -U +command line options after installing the predefined macro set. +The +.B -D +option defines +.I name +as a macro with the given +.IR value . +The +.B -U +option +.I undefines +the given macro +.IR name , +which may be one of the predefined macros. +.PP +.I M4 +in Inferno is more closely related to the original version in Seventh Edition UNIX +than the more elaborate relatives in System V and POSIX. +.SH "SEE ALSO" +B. W. Kernighan and D. M. Ritchie, +.I The M4 Macro Processor |