/[m4]/m4/doc/m4.info
ViewVC logotype

Diff of /m4/doc/m4.info

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1.1.1.2.6 by gary, Thu Feb 3 17:09:11 2005 UTC revision 1.1.1.1.2.7 by gary, Thu Mar 31 11:20:17 2005 UTC
# Line 1  Line 1 
1  This is m4.info, produced by makeinfo version 4.6 from m4.texinfo.  This is m4.info, produced by makeinfo version 4.7 from m4.texinfo.
2    
3    INFO-DIR-SECTION GNU programming tools
4  START-INFO-DIR-ENTRY  START-INFO-DIR-ENTRY
5  * m4: (m4).                     A powerful macro processor.  * m4: (m4).                     A powerful macro processor.
6  END-INFO-DIR-ENTRY  END-INFO-DIR-ENTRY
7    
8     This file documents the GNU `m4' utility.     This file documents GNU M4 1.4.2a.
9    
10     Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994, 2004 Free Software     Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994, 2004, 2005 Free
11  Foundation, Inc.  Software Foundation, Inc.
12    
13     Permission is granted to make and distribute verbatim copies of this     Permission is granted to make and distribute verbatim copies of this
14  manual provided the copyright notice and this permission notice are  manual provided the copyright notice and this permission notice are
# Line 26  translation approved by the Foundation. Line 27  translation approved by the Foundation.
27    
28  File: m4.info,  Node: Top,  Next: Preliminaries,  Prev: (dir),  Up: (dir)  File: m4.info,  Node: Top,  Next: Preliminaries,  Prev: (dir),  Up: (dir)
29    
30  GNU `m4'  GNU M4
31  ********  ******
32    
33  GNU `m4' is an implementation of the traditional UNIX macro processor.  GNU `m4' is an implementation of the traditional UNIX macro processor.
34  It is mostly SVR4 compatible, although it has some extensions (for  It is mostly SVR4 compatible, although it has some extensions (for
# Line 48  documentation.  However... Line 49  documentation.  However...
49     An experimental feature, which would improve `m4' usefulness, allows     An experimental feature, which would improve `m4' usefulness, allows
50  for changing the syntax for what is a "word" in `m4'.  You should use:  for changing the syntax for what is a "word" in `m4'.  You should use:
51       ./configure --enable-changeword       ./configure --enable-changeword
52       if you want this feature compiled in.  The current implementation
53  if you want this feature compiled in.  The current implementation slows  slows down `m4' considerably and is hardly acceptable.  So, it might go
54  down `m4' considerably and is hardly acceptable.  So, it might go away,  away, do not count on it yet.
 do not count on it yet.  
55    
56  * Menu:  * Menu:
57    
# Line 185  Compatibility with other versions of `m4 Line 185  Compatibility with other versions of `m4
185    
186  File: m4.info,  Node: Preliminaries,  Next: Syntax,  Prev: Top,  Up: Top  File: m4.info,  Node: Preliminaries,  Next: Syntax,  Prev: Top,  Up: Top
187    
188  Introduction and preliminaries  1 Introduction and preliminaries
189  ******************************  ********************************
190    
191  This first chapter explains what is GNU `m4', where `m4' comes from,  This first chapter explains what is GNU `m4', where `m4' comes from,
192  how to read and use this documentation, how to call the `m4' program  how to read and use this documentation, how to call the `m4' program
# Line 207  language. Line 207  language.
207    
208  File: m4.info,  Node: Intro,  Next: History,  Prev: Preliminaries,  Up: Preliminaries  File: m4.info,  Node: Intro,  Next: History,  Prev: Preliminaries,  Up: Preliminaries
209    
210  Introduction to `m4'  1.1 Introduction to `m4'
211  ====================  ========================
212    
213  `m4' is a macro processor, in the sense that it copies its input to the  `m4' is a macro processor, in the sense that it copies its input to the
214  output, expanding macros as it goes.  Macros are either builtin or  output, expanding macros as it goes.  Macros are either builtin or
# Line 238  the health of compulsive programmers. Line 238  the health of compulsive programmers.
238    
239  File: m4.info,  Node: History,  Next: Invoking m4,  Prev: Intro,  Up: Preliminaries  File: m4.info,  Node: History,  Next: Invoking m4,  Prev: Intro,  Up: Preliminaries
240    
241  Historical references  1.2 Historical references
242  =====================  =========================
243    
244  The historical notes included here are fairly incomplete, and not  The historical notes included here are fairly incomplete, and not
245  authoritative at all.  Please knowledgeable users help us to more  authoritative at all.  Please knowledgeable users help us to more
# Line 261  that is, the `ratfor' equivalent of `cpp Line 261  that is, the `ratfor' equivalent of `cpp
261    
262  File: m4.info,  Node: Invoking m4,  Next: Bugs,  Prev: History,  Up: Preliminaries  File: m4.info,  Node: Invoking m4,  Next: Bugs,  Prev: History,  Up: Preliminaries
263    
264  Invoking `m4'  1.3 Invoking `m4'
265  =============  =================
266    
267  The format of the `m4' command is:  The format of the `m4' command is:
268    
# Line 445  the command line. Line 445  the command line.
445    
446  File: m4.info,  Node: Bugs,  Next: Manual,  Prev: Invoking m4,  Up: Preliminaries  File: m4.info,  Node: Bugs,  Next: Manual,  Prev: Invoking m4,  Up: Preliminaries
447    
448  Problems and bugs  1.4 Problems and bugs
449  =================  =====================
450    
451  If you have problems with GNU `m4' or think you've found a bug, please  If you have problems with GNU `m4' or think you've found a bug, please
452  report it.  Before reporting a bug, make sure you've actually found a  report it.  Before reporting a bug, make sure you've actually found a
# Line 474  just obscure features, please report the Line 474  just obscure features, please report the
474    
475  File: m4.info,  Node: Manual,  Prev: Bugs,  Up: Preliminaries  File: m4.info,  Node: Manual,  Prev: Bugs,  Up: Preliminaries
476    
477  Using this manual  1.5 Using this manual
478  =================  =====================
479    
480  This manual contains a number of examples of `m4' input and output, and  This manual contains a number of examples of `m4' input and output, and
481  a simple notation is used to distinguish input, output and error  a simple notation is used to distinguish input, output and error
# Line 513  primitive is spelled within `m4'. Line 513  primitive is spelled within `m4'.
513    
514  File: m4.info,  Node: Syntax,  Next: Macros,  Prev: Preliminaries,  Up: Top  File: m4.info,  Node: Syntax,  Next: Macros,  Prev: Preliminaries,  Up: Top
515    
516  Lexical and syntactic conventions  2 Lexical and syntactic conventions
517  *********************************  ***********************************
518    
519  As `m4' reads its input, it separates it into "tokens".  A token is  As `m4' reads its input, it separates it into "tokens".  A token is
520  either a name, a quoted string, or any single character, that is not a  either a name, a quoted string, or any single character, that is not a
# Line 531  comments. Line 531  comments.
531    
532  File: m4.info,  Node: Names,  Next: Quoted strings,  Prev: Syntax,  Up: Syntax  File: m4.info,  Node: Names,  Next: Quoted strings,  Prev: Syntax,  Up: Syntax
533    
534  Names  2.1 Names
535  =====  =========
536    
537  A name is any sequence of letters, digits, and the character `_'  A name is any sequence of letters, digits, and the character `_'
538  (underscore), where the first character is not a digit.  If a name has  (underscore), where the first character is not a digit.  If a name has
# Line 544  Macros::). Line 544  Macros::).
544    
545  File: m4.info,  Node: Quoted strings,  Next: Other tokens,  Prev: Names,  Up: Syntax  File: m4.info,  Node: Quoted strings,  Next: Other tokens,  Prev: Names,  Up: Syntax
546    
547  Quoted strings  2.2 Quoted strings
548  ==============  ==================
549    
550  A quoted string is a sequence of characters surrounded by the quotes  A quoted string is a sequence of characters surrounded by the quotes
551  ``' and `'', where the number of start and end quotes within the string  ``' and `'', where the number of start and end quotes within the string
# Line 568  macro `changequote'.  *Note Changequote: Line 568  macro `changequote'.  *Note Changequote:
568    
569  File: m4.info,  Node: Other tokens,  Next: Comments,  Prev: Quoted strings,  Up: Syntax  File: m4.info,  Node: Other tokens,  Next: Comments,  Prev: Quoted strings,  Up: Syntax
570    
571  Other tokens  2.3 Other tokens
572  ============  ================
573    
574  Any character, that is neither a part of a name, nor of a quoted string,  Any character, that is neither a part of a name, nor of a quoted string,
575  is a token by itself.  is a token by itself.
# Line 577  is a token by itself. Line 577  is a token by itself.
577    
578  File: m4.info,  Node: Comments,  Prev: Other tokens,  Up: Syntax  File: m4.info,  Node: Comments,  Prev: Other tokens,  Up: Syntax
579    
580  Comments  2.4 Comments
581  ========  ============
582    
583  Comments in `m4' are normally delimited by the characters `#' and  Comments in `m4' are normally delimited by the characters `#' and
584  newline.  All characters between the comment delimiters are ignored,  newline.  All characters between the comment delimiters are ignored,
# Line 596  information. Line 596  information.
596    
597  File: m4.info,  Node: Macros,  Next: Definitions,  Prev: Syntax,  Up: Top  File: m4.info,  Node: Macros,  Next: Definitions,  Prev: Syntax,  Up: Top
598    
599  How to invoke macros  3 How to invoke macros
600  ********************  **********************
601    
602  This chapter covers macro invocation, macro arguments and how macro  This chapter covers macro invocation, macro arguments and how macro
603  expansion is treated.  expansion is treated.
# Line 613  expansion is treated. Line 613  expansion is treated.
613    
614  File: m4.info,  Node: Invocation,  Next: Inhibiting Invocation,  Prev: Macros,  Up: Macros  File: m4.info,  Node: Invocation,  Next: Inhibiting Invocation,  Prev: Macros,  Up: Macros
615    
616  Macro invocation  3.1 Macro invocation
617  ================  ====================
618    
619  Macro invocations has one of the forms  Macro invocations has one of the forms
620    
# Line 643  with no arguments. Line 643  with no arguments.
643    
644  File: m4.info,  Node: Inhibiting Invocation,  Next: Macro Arguments,  Prev: Invocation,  Up: Macros  File: m4.info,  Node: Inhibiting Invocation,  Next: Macro Arguments,  Prev: Invocation,  Up: Macros
645    
646  Preventing macro invocation  3.2 Preventing macro invocation
647  ===========================  ===============================
648    
649  An innovation of the `m4' language, compared to some of its  An innovation of the `m4' language, compared to some of its
650  predecessors (like Stratchey's `GPM', for example), is the ability to  predecessors (like Stratchey's `GPM', for example), is the ability to
# Line 725  the `divert' builtin would be called ins Line 725  the `divert' builtin would be called ins
725    
726  File: m4.info,  Node: Macro Arguments,  Next: Quoting Arguments,  Prev: Inhibiting Invocation,  Up: Macros  File: m4.info,  Node: Macro Arguments,  Next: Quoting Arguments,  Prev: Inhibiting Invocation,  Up: Macros
727    
728  Macro arguments  3.3 Macro arguments
729  ===============  ===================
730    
731  When a name is seen, and it has a macro definition, it will be expanded  When a name is seen, and it has a macro definition, it will be expanded
732  as a macro.  as a macro.
# Line 756  but trailing whitespace always is. Line 756  but trailing whitespace always is.
756    
757  File: m4.info,  Node: Quoting Arguments,  Next: Macro expansion,  Prev: Macro Arguments,  Up: Macros  File: m4.info,  Node: Quoting Arguments,  Next: Macro expansion,  Prev: Macro Arguments,  Up: Macros
758    
759  Quoting macro arguments  3.4 Quoting macro arguments
760  =======================  ===========================
761    
762  Each argument has leading unquoted whitespace removed.  Within each  Each argument has leading unquoted whitespace removed.  Within each
763  argument, all unquoted parentheses must match.  For example, if FOO is  argument, all unquoted parentheses must match.  For example, if FOO is
# Line 780  life a bit harder, if you are not carefu Line 780  life a bit harder, if you are not carefu
780    
781  File: m4.info,  Node: Macro expansion,  Prev: Quoting Arguments,  Up: Macros  File: m4.info,  Node: Macro expansion,  Prev: Quoting Arguments,  Up: Macros
782    
783  Macro expansion  3.5 Macro expansion
784  ===============  ===================
785    
786  When the arguments, if any, to a macro call have been collected, the  When the arguments, if any, to a macro call have been collected, the
787  macro is expanded, and the expansion text is pushed back onto the input  macro is expanded, and the expansion text is pushed back onto the input
# Line 800  will expand first to `bar', and when thi Line 800  will expand first to `bar', and when thi
800    
801  File: m4.info,  Node: Definitions,  Next: Conditionals,  Prev: Macros,  Up: Top  File: m4.info,  Node: Definitions,  Next: Conditionals,  Prev: Macros,  Up: Top
802    
803  How to define new macros  4 How to define new macros
804  ************************  **************************
805    
806  Macros can be defined, redefined and deleted in several different ways.  Macros can be defined, redefined and deleted in several different ways.
807  Also, it is possible to redefine a macro, without losing a previous  Also, it is possible to redefine a macro, without losing a previous
# Line 822  value, which can be brought back at a la Line 822  value, which can be brought back at a la
822    
823  File: m4.info,  Node: Define,  Next: Arguments,  Prev: Definitions,  Up: Definitions  File: m4.info,  Node: Define,  Next: Arguments,  Prev: Definitions,  Up: Definitions
824    
825  Defining a macro  4.1 Defining a macro
826  ================  ====================
827    
828  The normal way to define or redefine macros is to use the builtin  The normal way to define or redefine macros is to use the builtin
829  `define':  `define':
# Line 853  for details. Line 853  for details.
853    
854  File: m4.info,  Node: Arguments,  Next: Pseudo Arguments,  Prev: Define,  Up: Definitions  File: m4.info,  Node: Arguments,  Next: Pseudo Arguments,  Prev: Define,  Up: Definitions
855    
856  Arguments to macros  4.2 Arguments to macros
857  ===================  =======================
858    
859  Macros can have arguments.  The Nth argument is denoted by `$n' in the  Macros can have arguments.  The Nth argument is denoted by `$n' in the
860  expansion text, and is replaced by the Nth actual argument, when the  expansion text, and is replaced by the Nth actual argument, when the
# Line 904  string, and not a name. Line 904  string, and not a name.
904    
905  File: m4.info,  Node: Pseudo Arguments,  Next: Undefine,  Prev: Arguments,  Up: Definitions  File: m4.info,  Node: Pseudo Arguments,  Next: Undefine,  Prev: Arguments,  Up: Definitions
906    
907  Special arguments to macros  4.3 Special arguments to macros
908  ===========================  ===============================
909    
910  There is a special notation for the number of actual arguments supplied,  There is a special notation for the number of actual arguments supplied,
911  and for all the actual arguments.  and for all the actual arguments.
# Line 972  sign as a reference to an argument. Line 972  sign as a reference to an argument.
972    
973  File: m4.info,  Node: Undefine,  Next: Defn,  Prev: Pseudo Arguments,  Up: Definitions  File: m4.info,  Node: Undefine,  Next: Defn,  Prev: Pseudo Arguments,  Up: Definitions
974    
975  Deleting a macro  4.4 Deleting a macro
976  ================  ====================
977    
978  A macro definition can be removed with `undefine':  A macro definition can be removed with `undefine':
979    
# Line 1003  case, `undefine' does nothing. Line 1003  case, `undefine' does nothing.
1003    
1004  File: m4.info,  Node: Defn,  Next: Pushdef,  Prev: Undefine,  Up: Definitions  File: m4.info,  Node: Defn,  Next: Pushdef,  Prev: Undefine,  Up: Definitions
1005    
1006  Renaming macros  4.5 Renaming macros
1007  ===============  ===================
1008    
1009  It is possible to rename an already defined macro.  To do this, you need  It is possible to rename an already defined macro.  To do this, you need
1010  the builtin `defn':  the builtin `defn':
# Line 1039  the other name can still be used to acce Line 1039  the other name can still be used to acce
1039    
1040  File: m4.info,  Node: Pushdef,  Next: Indir,  Prev: Defn,  Up: Definitions  File: m4.info,  Node: Pushdef,  Next: Indir,  Prev: Defn,  Up: Definitions
1041    
1042  Temporarily redefining macros  4.6 Temporarily redefining macros
1043  =============================  =================================
1044    
1045  It is possible to redefine a macro temporarily, reverting to the  It is possible to redefine a macro temporarily, reverting to the
1046  previous definition at a later time.  This is done with the builtins  previous definition at a later time.  This is done with the builtins
# Line 1109  parameters. Line 1109  parameters.
1109    
1110  File: m4.info,  Node: Indir,  Next: Builtin,  Prev: Pushdef,  Up: Definitions  File: m4.info,  Node: Indir,  Next: Builtin,  Prev: Pushdef,  Up: Definitions
1111    
1112  Indirect call of macros  4.7 Indirect call of macros
1113  =======================  ===========================
1114    
1115  Any macro can be called indirectly with `indir':  Any macro can be called indirectly with `indir':
1116    
1117       indir(NAME, ...)       indir(NAME, ...)
1118       which results in a call to the macro NAME, which is passed the rest
1119  which results in a call to the macro NAME, which is passed the rest of  of the arguments.  This can be used to call macros with "illegal" names
 the arguments.  This can be used to call macros with "illegal" names  
1120  (`define' allows such names to be defined):  (`define' allows such names to be defined):
1121    
1122       define(`$$internal$macro', `Internal macro (name `$0')')       define(`$$internal$macro', `Internal macro (name `$0')')
# Line 1134  called through the builtin `indir'. Line 1133  called through the builtin `indir'.
1133    
1134  File: m4.info,  Node: Builtin,  Prev: Indir,  Up: Definitions  File: m4.info,  Node: Builtin,  Prev: Indir,  Up: Definitions
1135    
1136  Indirect call of builtins  4.8 Indirect call of builtins
1137  =========================  =============================
1138    
1139  Builtin macros can be called indirectly with `builtin':  Builtin macros can be called indirectly with `builtin':
1140    
1141       builtin(NAME, ...)       builtin(NAME, ...)
1142       which results in a call to the builtin NAME, which is passed the
1143  which results in a call to the builtin NAME, which is passed the rest  rest of the arguments.  This can be used, if NAME has been given
1144  of the arguments.  This can be used, if NAME has been given another  another definition that has covered the original.
 definition that has covered the original.  
1145    
1146     The macro `builtin' is recognized only with parameters.     The macro `builtin' is recognized only with parameters.
1147    
1148    
1149  File: m4.info,  Node: Conditionals,  Next: Debugging,  Prev: Definitions,  Up: Top  File: m4.info,  Node: Conditionals,  Next: Debugging,  Prev: Definitions,  Up: Top
1150    
1151  Conditionals, loops and recursion  5 Conditionals, loops and recursion
1152  *********************************  ***********************************
1153    
1154  Macros, expanding to plain text, perhaps with arguments, are not quite  Macros, expanding to plain text, perhaps with arguments, are not quite
1155  enough.  We would like to have macros expand to different things, based  enough.  We would like to have macros expand to different things, based
# Line 1169  true. Line 1167  true.
1167    
1168  File: m4.info,  Node: Ifdef,  Next: Ifelse,  Prev: Conditionals,  Up: Conditionals  File: m4.info,  Node: Ifdef,  Next: Ifelse,  Prev: Conditionals,  Up: Conditionals
1169    
1170  Testing macro definitions  5.1 Testing macro definitions
1171  =========================  =============================
1172    
1173  There are two different builtin conditionals in `m4'.  The first is  There are two different builtin conditionals in `m4'.  The first is
1174  `ifdef':  `ifdef':
# Line 1194  STRING-2.  If STRING-2 is omitted, it is Line 1192  STRING-2.  If STRING-2 is omitted, it is
1192    
1193  File: m4.info,  Node: Ifelse,  Next: Loops,  Prev: Ifdef,  Up: Conditionals  File: m4.info,  Node: Ifelse,  Next: Loops,  Prev: Ifdef,  Up: Conditionals
1194    
1195  Comparing strings  5.2 Comparing strings
1196  =================  =====================
1197    
1198  The other conditional, `ifelse', is much more powerful.  It can be used  The other conditional, `ifelse', is much more powerful.  It can be used
1199  as a way to introduce a long comment, as an if-else construct, or as a  as a way to introduce a long comment, as an if-else construct, or as a
# Line 1242  various kinds. Line 1240  various kinds.
1240    
1241  File: m4.info,  Node: Loops,  Prev: Ifelse,  Up: Conditionals  File: m4.info,  Node: Loops,  Prev: Ifelse,  Up: Conditionals
1242    
1243  Loops and recursion  5.3 Loops and recursion
1244  ===================  =======================
1245    
1246  There is no direct support for loops in `m4', but macros can be  There is no direct support for loops in `m4', but macros can be
1247  recursive.  There is no limit on the number of recursion levels, other  recursive.  There is no limit on the number of recursion levels, other
# Line 1334  the reader. Line 1332  the reader.
1332    
1333  File: m4.info,  Node: Debugging,  Next: Input Control,  Prev: Conditionals,  Up: Top  File: m4.info,  Node: Debugging,  Next: Input Control,  Prev: Conditionals,  Up: Top
1334    
1335  How to debug macros and input  6 How to debug macros and input
1336  *****************************  *******************************
1337    
1338  When writing macros for `m4', most of the time they woould not work as  When writing macros for `m4', most of the time they woould not work as
1339  intended (as is the case with most programming languages).  There is a  intended (as is the case with most programming languages).  There is a
# Line 1351  little support for macro debugging in `m Line 1349  little support for macro debugging in `m
1349    
1350  File: m4.info,  Node: Dumpdef,  Next: Trace,  Prev: Debugging,  Up: Debugging  File: m4.info,  Node: Dumpdef,  Next: Trace,  Prev: Debugging,  Up: Debugging
1351    
1352  Displaying macro definitions  6.1 Displaying macro definitions
1353  ============================  ================================
1354    
1355  If you want to see what a name expands into, you can use the builtin  If you want to see what a name expands into, you can use the builtin
1356  `dumpdef':  `dumpdef':
# Line 1383  the display. Line 1381  the display.
1381    
1382  File: m4.info,  Node: Trace,  Next: Debug Levels,  Prev: Dumpdef,  Up: Debugging  File: m4.info,  Node: Trace,  Next: Debug Levels,  Prev: Dumpdef,  Up: Debugging
1383    
1384  Tracing macro calls  6.2 Tracing macro calls
1385  ===================  =======================
1386    
1387  It is possible to trace macro calls and expansions through the builtins  It is possible to trace macro calls and expansions through the builtins
1388  `traceon' and `traceoff':  `traceon' and `traceoff':
# Line 1426  the display. Line 1424  the display.
1424    
1425  File: m4.info,  Node: Debug Levels,  Next: Debug Output,  Prev: Trace,  Up: Debugging  File: m4.info,  Node: Debug Levels,  Next: Debug Output,  Prev: Trace,  Up: Debugging
1426    
1427  Controlling debugging output  6.3 Controlling debugging output
1428  ============================  ================================
1429    
1430  The `-d' option to `m4' controls the amount of details presented, when  The `-d' option to `m4' controls the amount of details presented, when
1431  using the macros described in the preceding sections.  using the macros described in the preceding sections.
# Line 1486  flags. Line 1484  flags.
1484  control of the debugging output format:  control of the debugging output format:
1485    
1486       debugmode(opt FLAGS)       debugmode(opt FLAGS)
1487       The argument FLAGS should be a subset of the letters listed above.
1488  The argument FLAGS should be a subset of the letters listed above.  As  As special cases, if the argument starts with a `+', the flags are
1489  special cases, if the argument starts with a `+', the flags are added  added to the current debug flags, and if it starts with a `-', they are
 to the current debug flags, and if it starts with a `-', they are  
1490  removed.  If no argument is present, the debugging flags are set to  removed.  If no argument is present, the debugging flags are set to
1491  zero (as if no `-d' was given), and with an empty argument the flags  zero (as if no `-d' was given), and with an empty argument the flags
1492  are reset to the default.  are reset to the default.
# Line 1497  are reset to the default. Line 1494  are reset to the default.
1494    
1495  File: m4.info,  Node: Debug Output,  Prev: Debug Levels,  Up: Debugging  File: m4.info,  Node: Debug Output,  Prev: Debug Levels,  Up: Debugging
1496    
1497  Saving debugging output  6.4 Saving debugging output
1498  =======================  ===========================
1499    
1500  Debug and tracing output can be redirected to files using either the  Debug and tracing output can be redirected to files using either the
1501  `-o' option to `m4', or with the builtin macro `debugfile':  `-o' option to `m4', or with the builtin macro `debugfile':
1502    
1503       debugfile(opt FILENAME)       debugfile(opt FILENAME)
1504       will send all further debug and trace output to FILENAME.  If
1505  will send all further debug and trace output to FILENAME.  If FILENAME  FILENAME is empty, debug and trace output are discarded and if
1506  is empty, debug and trace output are discarded and if `debugfile' is  `debugfile' is called without any arguments, debug and trace output are
1507  called without any arguments, debug and trace output are sent to the  sent to the standard error output.
 standard error output.  
1508    
1509    
1510  File: m4.info,  Node: Input Control,  Next: File Inclusion,  Prev: Debugging,  Up: Top  File: m4.info,  Node: Input Control,  Next: File Inclusion,  Prev: Debugging,  Up: Top
1511    
1512  Input control  7 Input control
1513  *************  ***************
1514    
1515  This chapter describes various builtin macros for controlling the input  This chapter describes various builtin macros for controlling the input
1516  to `m4'.  to `m4'.
# Line 1530  to `m4'. Line 1526  to `m4'.
1526    
1527  File: m4.info,  Node: Dnl,  Next: Changequote,  Prev: Input Control,  Up: Input Control  File: m4.info,  Node: Dnl,  Next: Changequote,  Prev: Input Control,  Up: Input Control
1528    
1529  Deleting whitespace in input  7.1 Deleting whitespace in input
1530  ============================  ================================
1531    
1532  The builtin `dnl' reads and discards all characters, up to and  The builtin `dnl' reads and discards all characters, up to and
1533  including the first newline:  including the first newline:
1534    
1535       dnl       dnl
1536       and it is often used in connection with `define', to remove the
1537  and it is often used in connection with `define', to remove the newline  newline that follow the call to `define'.  Thus
 that follow the call to `define'.  Thus  
1538    
1539       define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.       define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
1540       foo       foo
# Line 1560  line containing it, will still be discar Line 1555  line containing it, will still be discar
1555    
1556  File: m4.info,  Node: Changequote,  Next: Changecom,  Prev: Dnl,  Up: Input Control  File: m4.info,  Node: Changequote,  Next: Changecom,  Prev: Dnl,  Up: Input Control
1557    
1558  Changing the quote characters  7.2 Changing the quote characters
1559  =============================  =================================
1560    
1561  The default quote delimiters can be changed with the builtin  The default quote delimiters can be changed with the builtin
1562  `changequote':  `changequote':
1563    
1564       changequote(opt START, opt END)       changequote(opt START, opt END)
1565       where START is the new start-quote delimiter and END is the new
 where START is the new start-quote delimiter and END is the new  
1566  end-quote delimiter.  If any of the arguments are missing, the default  end-quote delimiter.  If any of the arguments are missing, the default
1567  quotes (``' and `'') are used instead of the void arguments.  quotes (``' and `'') are used instead of the void arguments.
1568    
# Line 1613  the quoting mechanism. Line 1607  the quoting mechanism.
1607    
1608  File: m4.info,  Node: Changecom,  Next: Changeword,  Prev: Changequote,  Up: Input Control  File: m4.info,  Node: Changecom,  Next: Changeword,  Prev: Changequote,  Up: Input Control
1609    
1610  Changing comment delimiters  7.3 Changing comment delimiters
1611  ===========================  ===============================
1612    
1613  The default comment delimiters can be changed with the builtin macro  The default comment delimiters can be changed with the builtin macro
1614  `changecom':  `changecom':
1615    
1616       changecom(opt START, opt END)       changecom(opt START, opt END)
1617       where START is the new start-comment delimiter and END is the new
 where START is the new start-comment delimiter and END is the new  
1618  end-comment delimiter.  If any of the arguments are void, the default  end-comment delimiter.  If any of the arguments are void, the default
1619  comment delimiters (`#' and newline) are used instead of the void  comment delimiters (`#' and newline) are used instead of the void
1620  arguments.  The comment delimiters can be of any length.  arguments.  The comment delimiters can be of any length.
# Line 1656  mechanism completely. Line 1649  mechanism completely.
1649    
1650  File: m4.info,  Node: Changeword,  Next: M4wrap,  Prev: Changecom,  Up: Input Control  File: m4.info,  Node: Changeword,  Next: M4wrap,  Prev: Changecom,  Up: Input Control
1651    
1652  Changing the lexical structure of words  7.4 Changing the lexical structure of words
1653  =======================================  ===========================================
1654    
1655       The macro `changeword' and all associated functionnality is       The macro `changeword' and all associated functionnality is
1656       experimental.  It is only available if the `--enable-changeword'       experimental.  It is only available if the `--enable-changeword'
# Line 1742  factor of about seven. Line 1735  factor of about seven.
1735    
1736  File: m4.info,  Node: M4wrap,  Prev: Changeword,  Up: Input Control  File: m4.info,  Node: M4wrap,  Prev: Changeword,  Up: Input Control
1737    
1738  Saving input  7.5 Saving input
1739  ============  ================
1740    
1741  It is possible to `save' some text until the end of the normal input has  It is possible to `save' some text until the end of the normal input has
1742  been seen.  Text can be saved, to be read again by `m4' when the normal  been seen.  Text can be saved, to be read again by `m4' when the normal
# Line 1753  cleanup actions before normal exit, e.g. Line 1746  cleanup actions before normal exit, e.g.
1746     To save input text, use the builtin `m4wrap':     To save input text, use the builtin `m4wrap':
1747    
1748       m4wrap(STRING, ...)       m4wrap(STRING, ...)
1749       which stores STRING and the rest of the arguments in a safe place,
1750  which stores STRING and the rest of the arguments in a safe place, to  to be reread when end of input is reached.
 be reread when end of input is reached.  
1751    
1752       define(`cleanup', `This is the `cleanup' actions.       define(`cleanup', `This is the `cleanup' actions.
1753       ')       ')
# Line 1778  in which they were saved (LIFO--last in, Line 1770  in which they were saved (LIFO--last in,
1770    
1771  File: m4.info,  Node: File Inclusion,  Next: Diversions,  Prev: Input Control,  Up: Top  File: m4.info,  Node: File Inclusion,  Next: Diversions,  Prev: Input Control,  Up: Top
1772    
1773  File inclusion  8 File inclusion
1774  **************  ****************
1775    
1776  `m4' allows you to include named files at any point in the input.  `m4' allows you to include named files at any point in the input.
1777    
# Line 1791  File inclusion Line 1783  File inclusion
1783    
1784  File: m4.info,  Node: Include,  Next: Search Path,  Prev: File Inclusion,  Up: File Inclusion  File: m4.info,  Node: Include,  Next: Search Path,  Prev: File Inclusion,  Up: File Inclusion
1785    
1786  Including named files  8.1 Including named files
1787  =====================  =========================
1788    
1789  There are two builtin macros in `m4' for including files:  There are two builtin macros in `m4' for including files:
1790    
# Line 1820  include a file, if it exists, expanding Line 1812  include a file, if it exists, expanding
1812       Include file start       Include file start
1813       foo       foo
1814       Include file end       Include file end
1815       Normally file inclusion is used to insert the contents of a file
1816  Normally file inclusion is used to insert the contents of a file into  into the input stream.  The contents of the file will be read by `m4'
1817  the input stream.  The contents of the file will be read by `m4' and  and macro calls in the file will be expanded:
 macro calls in the file will be expanded:  
1818    
1819       define(`foo', `FOO')       define(`foo', `FOO')
1820       =>       =>
# Line 1856  given arguments. Line 1847  given arguments.
1847    
1848  File: m4.info,  Node: Search Path,  Prev: Include,  Up: File Inclusion  File: m4.info,  Node: Search Path,  Prev: Include,  Up: File Inclusion
1849    
1850  Searching for include files  8.2 Searching for include files
1851  ===========================  ===============================
1852    
1853  GNU `m4' allows included files to be found in other directories than  GNU `m4' allows included files to be found in other directories than
1854  the current working directory.  the current working directory.
# Line 1875  debug flag (*note Debug Levels::) can he Line 1866  debug flag (*note Debug Levels::) can he
1866    
1867  File: m4.info,  Node: Diversions,  Next: Text handling,  Prev: File Inclusion,  Up: Top  File: m4.info,  Node: Diversions,  Next: Text handling,  Prev: File Inclusion,  Up: Top
1868    
1869  Diverting and undiverting output  9 Diverting and undiverting output
1870  ********************************  **********************************
1871    
1872  Diversions are a way of temporarily saving output.  The output of `m4'  Diversions are a way of temporarily saving output.  The output of `m4'
1873  can at any time be diverted to a temporary file, and be reinserted into  can at any time be diverted to a temporary file, and be reinserted into
# Line 1903  number of available file descriptors. Line 1894  number of available file descriptors.
1894    
1895  File: m4.info,  Node: Divert,  Next: Undivert,  Prev: Diversions,  Up: Diversions  File: m4.info,  Node: Divert,  Next: Undivert,  Prev: Diversions,  Up: Diversions
1896    
1897  Diverting output  9.1 Diverting output
1898  ================  ====================
1899    
1900  Output is diverted using `divert':  Output is diverted using `divert':
1901    
# Line 1947  definitions.  Here is how to avoid them. Line 1938  definitions.  Here is how to avoid them.
1938    
1939  File: m4.info,  Node: Undivert,  Next: Divnum,  Prev: Divert,  Up: Diversions  File: m4.info,  Node: Undivert,  Next: Divnum,  Prev: Divert,  Up: Diversions
1940    
1941  Undiverting output  9.2 Undiverting output
1942  ==================  ======================
1943    
1944  Diverted text can be undiverted explicitly using the builtin `undivert':  Diverted text can be undiverted explicitly using the builtin `undivert':
1945    
# Line 2015  contains the word `bar': Line 2006  contains the word `bar':
2006    
2007  File: m4.info,  Node: Divnum,  Next: Cleardiv,  Prev: Undivert,  Up: Diversions  File: m4.info,  Node: Divnum,  Next: Cleardiv,  Prev: Undivert,  Up: Diversions
2008    
2009  Diversion numbers  9.3 Diversion numbers
2010  =================  =====================
2011    
2012  The builtin `divnum':  The builtin `divnum':
2013    
# Line 2044  undiverted text would otherwise be diver Line 2035  undiverted text would otherwise be diver
2035    
2036  File: m4.info,  Node: Cleardiv,  Prev: Divnum,  Up: Diversions  File: m4.info,  Node: Cleardiv,  Prev: Divnum,  Up: Diversions
2037    
2038  Discarding diverted text  9.4 Discarding diverted text
2039  ========================  ============================
2040    
2041  Often it is not known, when output is diverted, whether the diverted  Often it is not known, when output is diverted, whether the diverted
2042  text is actually needed.  Since all non-empty diversion are brought back  text is actually needed.  Since all non-empty diversion are brought back
# Line 2077  should try to see if you can find it and Line 2068  should try to see if you can find it and
2068    
2069  File: m4.info,  Node: Text handling,  Next: Arithmetic,  Prev: Diversions,  Up: Top  File: m4.info,  Node: Text handling,  Next: Arithmetic,  Prev: Diversions,  Up: Top
2070    
2071  Macros for text handling  10 Macros for text handling
2072  ************************  ***************************
2073    
2074  There are a number of builtins in `m4' for manipulating text in various  There are a number of builtins in `m4' for manipulating text in various
2075  ways, extracting substrings, searching, substituting, and so on.  ways, extracting substrings, searching, substituting, and so on.
# Line 2096  ways, extracting substrings, searching, Line 2087  ways, extracting substrings, searching,
2087    
2088  File: m4.info,  Node: Len,  Next: Index,  Prev: Text handling,  Up: Text handling  File: m4.info,  Node: Len,  Next: Index,  Prev: Text handling,  Up: Text handling
2089    
2090  Calculating length of strings  10.1 Calculating length of strings
2091  =============================  ==================================
2092    
2093  The length of a string can be calculated by `len':  The length of a string can be calculated by `len':
2094    
# Line 2115  which expands to the length of STRING, a Line 2106  which expands to the length of STRING, a
2106    
2107  File: m4.info,  Node: Index,  Next: Regexp,  Prev: Len,  Up: Text handling  File: m4.info,  Node: Index,  Next: Regexp,  Prev: Len,  Up: Text handling
2108    
2109  Searching for substrings  10.2 Searching for substrings
2110  ========================  =============================
2111    
2112  Searching for substrings is done with `index':  Searching for substrings is done with `index':
2113    
# Line 2136  not occur in STRING, `index' expands to Line 2127  not occur in STRING, `index' expands to
2127    
2128  File: m4.info,  Node: Regexp,  Next: Substr,  Prev: Index,  Up: Text handling  File: m4.info,  Node: Regexp,  Next: Substr,  Prev: Index,  Up: Text handling
2129    
2130  Searching for regular expressions  10.3 Searching for regular expressions
2131  =================================  ======================================
2132    
2133  Searching for regular expressions is done with the builtin `regexp':  Searching for regular expressions is done with the builtin `regexp':
2134    
# Line 2169  regular expression matched. Line 2160  regular expression matched.
2160    
2161  File: m4.info,  Node: Substr,  Next: Translit,  Prev: Regexp,  Up: Text handling  File: m4.info,  Node: Substr,  Next: Translit,  Prev: Regexp,  Up: Text handling
2162    
2163  Extracting substrings  10.4 Extracting substrings
2164  =====================  ==========================
2165    
2166  Substrings are extracted with `substr':  Substrings are extracted with `substr':
2167    
# Line 2190  is omitted.  The starting index of a str Line 2181  is omitted.  The starting index of a str
2181    
2182  File: m4.info,  Node: Translit,  Next: Patsubst,  Prev: Substr,  Up: Text handling  File: m4.info,  Node: Translit,  Next: Patsubst,  Prev: Substr,  Up: Text handling
2183    
2184  Translating characters  10.5 Translating characters
2185  ======================  ===========================
2186    
2187  Character translation is done with `translit':  Character translation is done with `translit':
2188    
# Line 2229  most common. Line 2220  most common.
2220    
2221  File: m4.info,  Node: Patsubst,  Next: Format,  Prev: Translit,  Up: Text handling  File: m4.info,  Node: Patsubst,  Next: Format,  Prev: Translit,  Up: Text handling
2222    
2223  Substituting text by regular expression  10.6 Substituting text by regular expression
2224  =======================================  ============================================
2225    
2226  Global substitution in a string is done by `patsubst':  Global substitution in a string is done by `patsubst':
2227    
2228       patsubst(STRING, REGEXP, opt REPLACEMENT)       patsubst(STRING, REGEXP, opt REPLACEMENT)
2229       which searches STRING for matches of REGEXP, and substitutes
 which searches STRING for matches of REGEXP, and substitutes  
2230  REPLACEMENT for each match.  The syntax for regular expressions is the  REPLACEMENT for each match.  The syntax for regular expressions is the
2231  same as in GNU Emacs.  same as in GNU Emacs.
2232    
# Line 2284  individual word or whole sentences, by s Line 2274  individual word or whole sentences, by s
2274    
2275  File: m4.info,  Node: Format,  Prev: Patsubst,  Up: Text handling  File: m4.info,  Node: Format,  Prev: Patsubst,  Up: Text handling
2276    
2277  Formatted output  10.7 Formatted output
2278  ================  =====================
2279    
2280  Formatted output can be made with `format':  Formatted output can be made with `format':
2281    
# Line 2327  the functioning of `printf', see the C L Line 2317  the functioning of `printf', see the C L
2317    
2318  File: m4.info,  Node: Arithmetic,  Next: UNIX commands,  Prev: Text handling,  Up: Top  File: m4.info,  Node: Arithmetic,  Next: UNIX commands,  Prev: Text handling,  Up: Top
2319    
2320  Macros for doing arithmetic  11 Macros for doing arithmetic
2321  ***************************  ******************************
2322    
2323  Integer arithmetic is included in `m4', with a C-like syntax.  As  Integer arithmetic is included in `m4', with a C-like syntax.  As
2324  convenient shorthands, there are builtins for simple increment and  convenient shorthands, there are builtins for simple increment and
# Line 2342  decrement operations. Line 2332  decrement operations.
2332    
2333  File: m4.info,  Node: Incr,  Next: Eval,  Prev: Arithmetic,  Up: Arithmetic  File: m4.info,  Node: Incr,  Next: Eval,  Prev: Arithmetic,  Up: Arithmetic
2334    
2335  Decrement and increment operators  11.1 Decrement and increment operators
2336  =================================  ======================================
2337    
2338  Increment and decrement of integers are supported using the builtins  Increment and decrement of integers are supported using the builtins
2339  `incr' and `decr':  `incr' and `decr':
# Line 2365  arguments. Line 2355  arguments.
2355    
2356  File: m4.info,  Node: Eval,  Prev: Incr,  Up: Arithmetic  File: m4.info,  Node: Eval,  Prev: Incr,  Up: Arithmetic
2357    
2358  Evaluating integer expressions  11.2 Evaluating integer expressions
2359  ==============================  ===================================
2360    
2361  Integer expressions are evaluated with `eval':  Integer expressions are evaluated with `eval':
2362    
# Line 2486  requested width. Line 2476  requested width.
2476    
2477  File: m4.info,  Node: UNIX commands,  Next: Miscellaneous,  Prev: Arithmetic,  Up: Top  File: m4.info,  Node: UNIX commands,  Next: Miscellaneous,  Prev: Arithmetic,  Up: Top
2478    
2479  Running UNIX commands  12 Running UNIX commands
2480  *********************  ************************
2481    
2482  There are a few builtin macros in `m4' that allow you to run UNIX  There are a few builtin macros in `m4' that allow you to run UNIX
2483  commands from within `m4'.  commands from within `m4'.
# Line 2502  commands from within `m4'. Line 2492  commands from within `m4'.
2492    
2493  File: m4.info,  Node: Syscmd,  Next: Esyscmd,  Prev: UNIX commands,  Up: UNIX commands  File: m4.info,  Node: Syscmd,  Next: Esyscmd,  Prev: UNIX commands,  Up: UNIX commands
2494    
2495  Executing simple commands  12.1 Executing simple commands
2496  =========================  ==============================
2497    
2498  Any shell command can be executed, using `syscmd':  Any shell command can be executed, using `syscmd':
2499    
# Line 2525  same as those of `m4'. Line 2515  same as those of `m4'.
2515    
2516  File: m4.info,  Node: Esyscmd,  Next: Sysval,  Prev: Syscmd,  Up: UNIX commands  File: m4.info,  Node: Esyscmd,  Next: Sysval,  Prev: Syscmd,  Up: UNIX commands
2517    
2518  Reading the output of commands  12.2 Reading the output of commands
2519  ==============================  ===================================
2520    
2521  If you want `m4' to read the output of a UNIX command, use `esyscmd':  If you want `m4' to read the output of a UNIX command, use `esyscmd':
2522    
# Line 2555  distribution, then: Line 2545  distribution, then:
2545    
2546  File: m4.info,  Node: Sysval,  Next: Maketemp,  Prev: Esyscmd,  Up: UNIX commands  File: m4.info,  Node: Sysval,  Next: Maketemp,  Prev: Esyscmd,  Up: UNIX commands
2547    
2548  Exit codes  12.3 Exit codes
2549  ==========  ===============
2550    
2551  To see whether a shell command succeeded, use `sysval':  To see whether a shell command succeeded, use `sysval':
2552    
# Line 2577  which expands to the exit status of the Line 2567  which expands to the exit status of the
2567    
2568  File: m4.info,  Node: Maketemp,  Prev: Sysval,  Up: UNIX commands  File: m4.info,  Node: Maketemp,  Prev: Sysval,  Up: UNIX commands
2569    
2570  Making names for temporary files  12.4 Making names for temporary files
2571  ================================  =====================================
2572    
2573  Commands specified to `syscmd' or `esyscmd' might need a temporary  Commands specified to `syscmd' or `esyscmd' might need a temporary
2574  file, for output or for some other purpose.  There is a builtin macro,  file, for output or for some other purpose.  There is a builtin macro,
# Line 2599  the `m4' process, in order to make the f Line 2589  the `m4' process, in order to make the f
2589    
2590  File: m4.info,  Node: Miscellaneous,  Next: Frozen files,  Prev: UNIX commands,  Up: Top  File: m4.info,  Node: Miscellaneous,  Next: Frozen files,  Prev: UNIX commands,  Up: Top
2591    
2592  Miscellaneous builtin macros  13 Miscellaneous builtin macros
2593  ****************************  *******************************
2594    
2595  This chapter describes various builtins, that do not really belong in  This chapter describes various builtins, that do not really belong in
2596  any of the previous chapters.  any of the previous chapters.
# Line 2613  any of the previous chapters. Line 2603  any of the previous chapters.
2603    
2604  File: m4.info,  Node: Errprint,  Next: M4exit,  Prev: Miscellaneous,  Up: Miscellaneous  File: m4.info,  Node: Errprint,  Next: M4exit,  Prev: Miscellaneous,  Up: Miscellaneous
2605    
2606  Printing error messages  13.1 Printing error messages
2607  =======================  ============================
2608    
2609  You can print error messages using `errprint':  You can print error messages using `errprint':
2610    
2611       errprint(MESSAGE, ...)       errprint(MESSAGE, ...)
2612       which simply prints MESSAGE and the rest of the arguments on the
 which simply prints MESSAGE and the rest of the arguments on the  
2613  standard error output.  standard error output.
2614    
2615     The expansion of `errprint' is void.     The expansion of `errprint' is void.
# Line 2639  utility builtins exist: Line 2628  utility builtins exist:
2628    
2629       __file__       __file__
2630       __line__       __line__
2631       which expands to the quoted name of the current input file, and the
 which expands to the quoted name of the current input file, and the  
2632  current input line number in that file.  current input line number in that file.
2633    
2634       errprint(`m4:'__file__:__line__: `Input error       errprint(`m4:'__file__:__line__: `Input error
# Line 2651  current input line number in that file. Line 2639  current input line number in that file.
2639    
2640  File: m4.info,  Node: M4exit,  Prev: Errprint,  Up: Miscellaneous  File: m4.info,  Node: M4exit,  Prev: Errprint,  Up: Miscellaneous
2641    
2642  Exiting from `m4'  13.2 Exiting from `m4'
2643  =================  ======================
2644    
2645  If you need to exit from `m4' before the entire input has been read,  If you need to exit from `m4' before the entire input has been read,
2646  you can use `m4exit':  you can use `m4exit':
2647    
2648       m4exit(opt CODE)       m4exit(opt CODE)
2649       which causes `m4' to exit, with exit code CODE.  If CODE is left
2650  which causes `m4' to exit, with exit code CODE.  If CODE is left out,  out, the exit code is zero.
 the exit code is zero.  
2651    
2652       define(`fatal_error', `errprint(`m4: '__file__: __line__`: fatal error: $*       define(`fatal_error', `errprint(`m4: '__file__: __line__`: fatal error: $*
2653       ')m4exit(1)')       ')m4exit(1)')
# Line 2676  not followed, e.g., diverted text is not Line 2663  not followed, e.g., diverted text is not
2663    
2664  File: m4.info,  Node: Frozen files,  Next: Compatibility,  Prev: Miscellaneous,  Up: Top  File: m4.info,  Node: Frozen files,  Next: Compatibility,  Prev: Miscellaneous,  Up: Top
2665    
2666  Fast loading of frozen states  14 Fast loading of frozen states
2667  *****************************  ********************************
2668    
2669  Some bigger `m4' applications may be built over a common base  Some bigger `m4' applications may be built over a common base
2670  containing hundreds of definitions and other costly initializations.  containing hundreds of definitions and other costly initializations.
# Line 2791  decimal.  The directives are: Line 2778  decimal.  The directives are:
2778    
2779  File: m4.info,  Node: Compatibility,  Next: Concept index,  Prev: Frozen files,  Up: Top  File: m4.info,  Node: Compatibility,  Next: Concept index,  Prev: Frozen files,  Up: Top
2780    
2781  Compatibility with other versions of `m4'  15 Compatibility with other versions of `m4'
2782  *****************************************  ********************************************
2783    
2784  This chapter describes the differences between this implementation of  This chapter describes the differences between this implementation of
2785  `m4', and the implementation found under UNIX, notably System V,  `m4', and the implementation found under UNIX, notably System V,
# Line 2810  made to summarize these here. Line 2797  made to summarize these here.
2797    
2798  File: m4.info,  Node: Extensions,  Next: Incompatibilities,  Prev: Compatibility,  Up: Compatibility  File: m4.info,  Node: Extensions,  Next: Incompatibilities,  Prev: Compatibility,  Up: Compatibility
2799    
2800  Extensions in GNU `m4'  15.1 Extensions in GNU `m4'
2801  ======================  ===========================
2802    
2803  This version of `m4' contains a few facilities, that do not exist in  This version of `m4' contains a few facilities, that do not exist in
2804  System V `m4'.  These extra facilities are all suppressed by using the  System V `m4'.  These extra facilities are all suppressed by using the
# Line 2868  extensive than in most other versions of Line 2855  extensive than in most other versions of
2855    
2856  File: m4.info,  Node: Incompatibilities,  Next: Other Incompat,  Prev: Extensions,  Up: Compatibility  File: m4.info,  Node: Incompatibilities,  Next: Other Incompat,  Prev: Extensions,  Up: Compatibility
2857    
2858  Facilities in System V `m4' not in GNU `m4'  15.2 Facilities in System V `m4' not in GNU `m4'
2859  ===========================================  ================================================
2860    
2861  The version of `m4' from System V contains a few facilities that have  The version of `m4' from System V contains a few facilities that have
2862  not been implemented in GNU `m4' yet.  not been implemented in GNU `m4' yet.
# Line 2880  not been implemented in GNU `m4' yet. Line 2867  not been implemented in GNU `m4' yet.
2867    
2868  File: m4.info,  Node: Other Incompat,  Prev: Incompatibilities,  Up: Compatibility  File: m4.info,  Node: Other Incompat,  Prev: Incompatibilities,  Up: Compatibility
2869    
2870  Other incompatibilities  15.3 Other incompatibilities
2871  =======================  ============================
2872    
2873  There are a few other incompatibilities between this implementation of  There are a few other incompatibilities between this implementation of
2874  `m4', and the System V version.  `m4', and the System V version.
# Line 2934  File: m4.info,  Node: Concept index,  Ne Line 2921  File: m4.info,  Node: Concept index,  Ne
2921  Concept index  Concept index
2922  *************  *************
2923    
2924    [index]
2925  * Menu:  * Menu:
2926    
2927  * Arguments to macros:                   Arguments.  * arguments to macros:                   Macro Arguments.     (line   6)
2928  * arguments to macros:                   Macro Arguments.  * Arguments to macros:                   Arguments.           (line   6)
2929  * arguments to macros, special:          Pseudo Arguments.  * arguments to macros, special:          Pseudo Arguments.    (line   6)
2930  * arguments, quoted macro:               Quoting Arguments.  * arguments, quoted macro:               Quoting Arguments.   (line   6)
2931  * arithmetic:                            Arithmetic.  * arithmetic:                            Arithmetic.          (line   6)
2932  * builtins, indirect call of:            Builtin.  * builtins, indirect call of:            Builtin.             (line   6)
2933  * call of builtins, indirect:            Builtin.  * call of builtins, indirect:            Builtin.             (line   6)
2934  * call of macros, indirect:              Indir.  * call of macros, indirect:              Indir.               (line   6)
2935  * changing comment delimiters:           Changecom.  * changing comment delimiters:           Changecom.           (line   6)
2936  * changing the quote delimiters:         Changequote.  * changing the quote delimiters:         Changequote.         (line   6)
2937  * characters, translating:               Translit.  * characters, translating:               Translit.            (line   6)
2938  * command line, filenames on the:        Invoking m4.  * command line, filenames on the:        Invoking m4.         (line 176)
2939  * command line, macro definitions on the: Invoking m4.  * command line, macro definitions on the: Invoking m4.        (line 143)
2940  * command line, options:                 Invoking m4.  * command line, options:                 Invoking m4.         (line  10)
2941  * commands, exit code from UNIX:         Sysval.  * commands, exit code from UNIX:         Sysval.              (line   6)
2942  * commands, running UNIX:                UNIX commands.  * commands, running UNIX:                UNIX commands.       (line   6)
2943  * comment delimiters, changing:          Changecom.  * comment delimiters, changing:          Changecom.           (line   6)
2944  * comments:                              Comments.  * comments:                              Comments.            (line   6)
2945  * comments, copied to output:            Changecom.  * comments, copied to output:            Changecom.           (line  28)
2946  * comparing strings:                     Ifelse.  * comparing strings:                     Ifelse.              (line   6)
2947  * compatibility:                         Compatibility.  * compatibility:                         Compatibility.       (line   6)
2948  * conditionals:                          Ifdef.  * conditionals:                          Ifdef.               (line   6)
2949  * controlling debugging output:          Debug Levels.  * controlling debugging output:          Debug Levels.        (line   6)
2950  * counting loops:                        Loops.  * counting loops:                        Loops.               (line  42)
2951  * debugging output, controlling:         Debug Levels.  * debugging output, controlling:         Debug Levels.        (line   6)
2952  * debugging output, saving:              Debug Output.  * debugging output, saving:              Debug Output.        (line   6)
2953  * decrement operator:                    Incr.  * decrement operator:                    Incr.                (line   6)
2954  * defining new macros:                   Definitions.  * defining new macros:                   Definitions.         (line   6)
2955  * definitions, displaying macro:         Dumpdef.  * definitions, displaying macro:         Dumpdef.             (line   6)
2956  * deleting macros:                       Undefine.  * deleting macros:                       Undefine.            (line   6)
2957  * deleting whitespace in input:          Dnl.  * deleting whitespace in input:          Dnl.                 (line   6)
2958  * discarding diverted text:              Cleardiv.  * discarding diverted text:              Cleardiv.            (line   6)
2959  * displaying macro definitions:          Dumpdef.  * displaying macro definitions:          Dumpdef.             (line   6)
2960  * diversion numbers:                     Divnum.  * diversion numbers:                     Divnum.              (line   6)
2961  * diverted text, discarding:             Cleardiv.  * diverted text, discarding:             Cleardiv.            (line   6)
2962  * diverting output to files:             Divert.  * diverting output to files:             Divert.              (line   6)
2963  * dumping into frozen file:              Frozen files.  * dumping into frozen file:              Frozen files.        (line   6)
2964  * error messages, printing:              Errprint.  * error messages, printing:              Errprint.            (line   6)
2965  * evaluation, of integer expressions:    Eval.  * evaluation, of integer expressions:    Eval.                (line   6)
2966  * executing UNIX commands:               UNIX commands.  * executing UNIX commands:               UNIX commands.       (line   6)
2967  * exit code from UNIX commands:          Sysval.  * exit code from UNIX commands:          Sysval.              (line   6)
2968  * exiting from m4:                       M4exit.  * exiting from m4:                       M4exit.              (line   6)
2969  * expansion of macros:                   Macro expansion.  * expansion of macros:                   Macro expansion.     (line   6)
2970  * expansion, tracing macro:              Trace.  * expansion, tracing macro:              Trace.               (line   6)
2971  * expressions, evaluation of integer:    Eval.  * expressions, evaluation of integer:    Eval.                (line   6)
2972  * extracting substrings:                 Substr.  * extracting substrings:                 Substr.              (line   6)
2973  * fast loading of frozen files:          Frozen files.  * fast loading of frozen files:          Frozen files.        (line   6)
2974  * file inclusion <1>:                    Undivert.  * file inclusion <1>:                    Undivert.            (line  53)
2975  * file inclusion:                        File Inclusion.  * file inclusion:                        File Inclusion.      (line   6)
2976  * filenames, on the command line:        Invoking m4.  * filenames, on the command line:        Invoking m4.         (line 176)
2977  * files, diverting output to:            Divert.  * files, diverting output to:            Divert.              (line   6)
2978  * files, names of temporary:             Maketemp.  * files, names of temporary:             Maketemp.            (line   6)
2979  * forloops:                              Loops.  * forloops:                              Loops.               (line  42)
2980  * formatted output:                      Format.  * formatted output:                      Format.              (line   6)
2981  * frozen files for fast loading:         Frozen files.  * frozen files for fast loading:         Frozen files.        (line   6)
2982  * GNU extensions <1>:                    Extensions.  * GNU extensions <1>:                    Undivert.            (line  53)
2983  * GNU extensions <2>:                    Frozen files.  * GNU extensions <2>:                    Patsubst.            (line   6)
2984  * GNU extensions <3>:                    Esyscmd.  * GNU extensions <3>:                    Extensions.          (line   6)
2985  * GNU extensions <4>:                    Format.  * GNU extensions <4>:                    Search Path.         (line   6)
2986  * GNU extensions <5>:                    Patsubst.  * GNU extensions <5>:                    Frozen files.        (line   6)
2987  * GNU extensions <6>:                    Regexp.  * GNU extensions <6>:                    Indir.               (line   6)
2988  * GNU extensions <7>:                    Undivert.  * GNU extensions <7>:                    Regexp.              (line   6)
2989  * GNU extensions <8>:                    Search Path.  * GNU extensions <8>:                    Debug Output.        (line   6)
2990  * GNU extensions <9>:                    Debug Output.  * GNU extensions <9>:                    Debug Levels.        (line  59)
2991  * GNU extensions <10>:                   Debug Levels.  * GNU extensions <10>:                   Builtin.             (line   6)
2992  * GNU extensions <11>:                   Builtin.  * GNU extensions <11>:                   Format.              (line   6)
2993  * GNU extensions <12>:                   Indir.  * GNU extensions <12>:                   Esyscmd.             (line   6)
2994  * GNU extensions:                        Arguments.  * GNU extensions:                        Arguments.           (line  28)
2995  * included files, search path for:       Search Path.  * included files, search path for:       Search Path.         (line   6)
2996  * inclusion, of files <1>:               Undivert.  * inclusion, of files <1>:               File Inclusion.      (line   6)
2997  * inclusion, of files:                   File Inclusion.  * inclusion, of files:                   Undivert.            (line  53)
2998  * increment operator:                    Incr.  * increment operator:                    Incr.                (line   6)
2999  * indirect call of builtins:             Builtin.  * indirect call of builtins:             Builtin.             (line   6)
3000  * indirect call of macros:               Indir.  * indirect call of macros:               Indir.               (line   6)
3001  * initialization, frozen states:         Frozen files.  * initialization, frozen states:         Frozen files.        (line   6)
3002  * input tokens:                          Syntax.  * input tokens:                          Syntax.              (line   6)
3003  * input, saving:                         M4wrap.  * input, saving:                         M4wrap.              (line   6)
3004  * integer arithmetic:                    Arithmetic.  * integer arithmetic:                    Arithmetic.          (line   6)
3005  * integer expression evaluation:         Eval.  * integer expression evaluation:         Eval.                (line   6)
3006  * length of strings:                     Len.  * length of strings:                     Len.                 (line   6)
3007  * lexical structure of words:            Changeword.  * lexical structure of words:            Changeword.          (line   6)
3008  * loops:                                 Loops.  * loops:                                 Loops.               (line  10)
3009  * loops, counting:                       Loops.  * loops, counting:                       Loops.               (line  42)
3010  * macro definitions, on the command line: Invoking m4.  * macro definitions, on the command line: Invoking m4.        (line 143)
3011  * macro expansion, tracing:              Trace.  * macro expansion, tracing:              Trace.               (line   6)
3012  * macro invocation:                      Invocation.  * macro invocation:                      Invocation.          (line   6)
3013  * macros, arguments to <1>:              Arguments.  * macros, arguments to <1>:              Arguments.           (line   6)
3014  * macros, arguments to:                  Macro Arguments.  * macros, arguments to:                  Macro Arguments.     (line   6)
3015  * macros, displaying definitions:        Dumpdef.  * macros, displaying definitions:        Dumpdef.             (line   6)
3016  * macros, expansion of:                  Macro expansion.  * macros, expansion of:                  Macro expansion.     (line   6)
3017  * macros, how to define new:             Definitions.  * macros, how to define new:             Definitions.         (line   6)
3018  * macros, how to delete:                 Undefine.  * macros, how to delete:                 Undefine.            (line   6)
3019  * macros, how to rename:                 Defn.  * macros, how to rename:                 Defn.                (line   6)
3020  * macros, indirect call of:              Indir.  * macros, indirect call of:              Indir.               (line   6)
3021  * macros, quoted arguments to:           Quoting Arguments.  * macros, quoted arguments to:           Quoting Arguments.   (line   6)
3022  * macros, recursive:                     Loops.  * macros, recursive:                     Loops.               (line   6)
3023  * macros, special arguments to:          Pseudo Arguments.  * macros, special arguments to:          Pseudo Arguments.    (line   6)
3024  * macros, temporary redefinition of:     Pushdef.  * macros, temporary redefinition of:     Pushdef.             (line   6)
3025  * messages, printing error:              Errprint.  * messages, printing error:              Errprint.            (line   6)
3026  * multibranches:                         Ifelse.  * multibranches:                         Ifelse.              (line  33)
3027  * names:                                 Names.  * names:                                 Names.               (line   6)
3028  * options, command line:                 Invoking m4.  * options, command line:                 Invoking m4.         (line  10)
3029  * output, diverting to files:            Divert.  * output, diverting to files:            Divert.              (line   6)
3030  * output, formatted:                     Format.  * output, formatted:                     Format.              (line   6)
3031  * output, saving debugging:              Debug Output.  * output, saving debugging:              Debug Output.        (line   6)
3032  * pattern substitution:                  Patsubst.  * pattern substitution:                  Patsubst.            (line   6)
3033  * printing error messages:               Errprint.  * printing error messages:               Errprint.            (line   6)
3034  * quote delimiters, changing the:        Changequote.  * quote delimiters, changing the:        Changequote.         (line   6)
3035  * quoted macro arguments:                Quoting Arguments.  * quoted macro arguments:                Quoting Arguments.   (line   6)
3036  * quoted string:                         Quoted strings.  * quoted string:                         Quoted strings.      (line   6)
3037  * recursive macros:                      Loops.  * recursive macros:                      Loops.               (line   6)
3038  * redefinition of macros, temporary:     Pushdef.  * redefinition of macros, temporary:     Pushdef.             (line   6)
3039  * regular expressions <1>:               Patsubst.  * regular expressions <1>:               Patsubst.            (line   6)
3040  * regular expressions:                   Regexp.  * regular expressions:                   Regexp.              (line   6)
3041  * reloading a frozen file:               Frozen files.  * reloading a frozen file:               Frozen files.        (line   6)
3042  * renaming macros:                       Defn.  * renaming macros:                       Defn.                (line   6)
3043  * running UNIX commands:                 UNIX commands.  * running UNIX commands:                 UNIX commands.       (line   6)
3044  * saving debugging output:               Debug Output.  * saving debugging output:               Debug Output.        (line   6)
3045  * saving input:                          M4wrap.  * saving input:                          M4wrap.              (line   6)
3046  * search path for included files:        Search Path.  * search path for included files:        Search Path.         (line   6)
3047  * special arguments to macros:           Pseudo Arguments.  * special arguments to macros:           Pseudo Arguments.    (line   6)
3048  * strings, length of:                    Len.  * strings, length of:                    Len.                 (line   6)
3049  * substitution by regular expression:    Patsubst.  * substitution by regular expression:    Patsubst.            (line   6)
3050  * substrings, extracting:                Substr.  * substrings, extracting:                Substr.              (line   6)
3051  * temporary filenames:                   Maketemp.  * temporary filenames:                   Maketemp.            (line   6)
3052  * temporary redefinition of macros:      Pushdef.  * temporary redefinition of macros:      Pushdef.             (line   6)
3053  * tokens:                                Syntax.  * tokens:                                Syntax.              (line   6)
3054  * tracing macro expansion:               Trace.  * tracing macro expansion:               Trace.               (line   6)
3055  * translating characters:                Translit.  * translating characters:                Translit.            (line   6)
3056  * undefining macros:                     Undefine.  * undefining macros:                     Undefine.            (line   6)
3057  * UNIX commands, exit code from:         Sysval.  * UNIX commands, exit code from:         Sysval.              (line   6)
3058  * UNIX commands, running:                UNIX commands.  * UNIX commands, running:                UNIX commands.       (line   6)
3059  * words, lexical structure of:           Changeword.  * words, lexical structure of:           Changeword.          (line   6)
3060    
3061    
3062  File: m4.info,  Node: Macro index,  Prev: Concept index,  Up: Top  File: m4.info,  Node: Macro index,  Prev: Concept index,  Up: Top
# Line 3080  References are exclusively to the places Line 3068  References are exclusively to the places
3068  the first time.  Names starting and ending with `__' have these  the first time.  Names starting and ending with `__' have these
3069  characters removed in the index.  characters removed in the index.
3070    
3071    [index]
3072  * Menu:  * Menu:
3073    
3074  * builtin:                               Builtin.  * builtin:                               Builtin.              (line  6)
3075  * changecom:                             Changecom.  * changecom:                             Changecom.            (line  6)
3076  * changequote:                           Changequote.  * changequote:                           Changequote.          (line  6)
3077  * changeword:                            Changeword.  * changeword:                            Changeword.           (line  6)
3078  * debugfile:                             Debug Output.  * debugfile:                             Debug Output.         (line  6)
3079  * debugmode:                             Debug Levels.  * debugmode:                             Debug Levels.         (line 59)
3080  * decr:                                  Incr.  * decr:                                  Incr.                 (line  6)
3081  * define:                                Define.  * define:                                Define.               (line  6)
3082  * defn:                                  Defn.  * defn:                                  Defn.                 (line  6)
3083  * divert:                                Divert.  * divert:                                Divert.               (line  6)
3084  * divnum:                                Divnum.  * divnum:                                Divnum.               (line  6)
3085  * dnl:                                   Dnl.  * dnl:                                   Dnl.                  (line  6)
3086  * dumpdef:                               Dumpdef.  * dumpdef:                               Dumpdef.              (line  6)
3087  * errprint:                              Errprint.  * errprint:                              Errprint.             (line  6)
3088  * esyscmd:                               Esyscmd.  * esyscmd:                               Esyscmd.              (line  6)
3089  * eval:                                  Eval.  * eval:                                  Eval.                 (line  6)
3090  * file:                                  Errprint.  * file:                                  Errprint.             (line 26)
3091  * format:                                Format.  * format:                                Format.               (line  6)
3092  * gnu:                                   Other Incompat.  * gnu:                                   Other Incompat.       (line 44)
3093  * ifdef:                                 Ifdef.  * ifdef:                                 Ifdef.                (line  6)
3094  * ifelse:                                Ifelse.  * ifelse:                                Ifelse.               (line  6)
3095  * include:                               Include.  * include:                               Include.              (line  6)
3096  * incr:                                  Incr.  * incr:                                  Incr.                 (line  6)
3097  * index:                                 Index.  * index:                                 Index.                (line  6)
3098  * indir:                                 Indir.  * indir:                                 Indir.                (line  6)
3099  * len:                                   Len.  * len:                                   Len.                  (line  6)
3100  * line:                                  Errprint.  * line:                                  Errprint.             (line 26)
3101  * m4exit:                                M4exit.  * m4exit:                                M4exit.               (line  6)
3102  * m4wrap:                                M4wrap.  * m4wrap:                                M4wrap.               (line  6)
3103  * maketemp:                              Maketemp.  * maketemp:                              Maketemp.             (line  6)
3104  * patsubst:                              Patsubst.  * patsubst:                              Patsubst.             (line  6)
3105  * popdef:                                Pushdef.  * popdef:                                Pushdef.              (line  7)
3106  * pushdef:                               Pushdef.  * pushdef:                               Pushdef.              (line  7)
3107  * regexp:                                Regexp.  * regexp:                                Regexp.               (line  6)
3108  * shift:                                 Loops.  * shift:                                 Loops.                (line 13)
3109  * sinclude:                              Include.  * sinclude:                              Include.              (line  6)
3110  * substr:                                Substr.  * substr:                                Substr.               (line  6)
3111  * syscmd:                                Syscmd.  * syscmd:                                Syscmd.               (line  6)
3112  * sysval:                                Sysval.  * sysval:                                Sysval.               (line  6)
3113  * traceoff:                              Trace.  * traceoff:                              Trace.                (line  6)
3114  * traceon:                               Trace.  * traceon:                               Trace.                (line  6)
3115  * translit:                              Translit.  * translit:                              Translit.             (line  6)
3116  * undefine:                              Undefine.  * undefine:                              Undefine.             (line  6)
3117  * undivert:                              Undivert.  * undivert:                              Undivert.             (line  6)
3118  * unix:                                  Other Incompat.  * unix:                                  Other Incompat.       (line 47)
3119    
3120    
3121    
3122  Tag Table:  Tag Table:
3123  Node: Top947  Node: Top985
3124  Node: Preliminaries6948  Node: Preliminaries6984
3125  Node: Intro7670  Node: Intro7710
3126  Node: History9276  Node: History9324
3127  Node: Invoking m410194  Node: Invoking m410250
3128  Node: Bugs16987  Node: Bugs17051
3129  Node: Manual18252  Node: Manual18324
3130  Node: Syntax19615  Node: Syntax19695
3131  Node: Names20199  Node: Names20283
3132  Node: Quoted strings20569  Node: Quoted strings20661
3133  Node: Other tokens21151  Node: Other tokens21251
3134  Node: Comments21365  Node: Comments21473
3135  Node: Macros22025  Node: Macros22141
3136  Node: Invocation22515  Node: Invocation22635
3137  Node: Inhibiting Invocation23323  Node: Inhibiting Invocation23451
3138  Node: Macro Arguments26466  Node: Macro Arguments26602
3139  Node: Quoting Arguments27727  Node: Quoting Arguments27871
3140  Node: Macro expansion28529  Node: Macro expansion28681
3141  Node: Definitions29189  Node: Definitions29349
3142  Node: Define29962  Node: Define30126
3143  Node: Arguments30770  Node: Arguments30942
3144  Node: Pseudo Arguments32247  Node: Pseudo Arguments32427
3145  Node: Undefine34095  Node: Undefine34283
3146  Node: Defn34754  Node: Defn34950
3147  Node: Pushdef35908  Node: Pushdef36112
3148  Node: Indir37741  Node: Indir37953
3149  Node: Builtin38500  Node: Builtin38722
3150  Node: Conditionals38941  Node: Conditionals39173
3151  Node: Ifdef39645  Node: Ifdef39881
3152  Node: Ifelse40411  Node: Ifelse40655
3153  Node: Loops42174  Node: Loops42426
3154  Node: Debugging45443  Node: Debugging45703
3155  Node: Dumpdef46019  Node: Dumpdef46283
3156  Node: Trace46865  Node: Trace47137
3157  Node: Debug Levels48242  Node: Debug Levels48522
3158  Node: Debug Output50623  Node: Debug Output50912
3159  Node: Input Control51140  Node: Input Control51439
3160  Node: Dnl51674  Node: Dnl51977
3161  Node: Changequote52796  Node: Changequote53109
3162  Node: Changecom54157  Node: Changecom54480
3163  Node: Changeword55438  Node: Changeword55771
3164  Node: M4wrap58647  Node: M4wrap58988
3165  Node: File Inclusion59846  Node: File Inclusion60197
3166  Node: Include60159  Node: Include60514
3167  Node: Search Path62084  Node: Search Path62449
3168  Node: Diversions62867  Node: Diversions63240
3169  Node: Divert64101  Node: Divert64478
3170  Node: Undivert65230  Node: Undivert65615
3171  Node: Divnum67161  Node: Divnum67554
3172  Node: Cleardiv67703  Node: Cleardiv68104
3173  Node: Text handling68736  Node: Text handling69145
3174  Node: Len69453  Node: Len69868
3175  Node: Index69848  Node: Index70273
3176  Node: Regexp70430  Node: Regexp70865
3177  Node: Substr71518  Node: Substr71963
3178  Node: Translit72135  Node: Translit72590
3179  Node: Patsubst73575  Node: Patsubst74040
3180  Node: Format75663  Node: Format76140
3181  Node: Arithmetic77149  Node: Arithmetic77636
3182  Node: Incr77591  Node: Incr78084
3183  Node: Eval78092  Node: Eval78595
3184  Node: UNIX commands81088  Node: UNIX commands81601
3185  Node: Syscmd81556  Node: Syscmd82075
3186  Node: Esyscmd82267  Node: Esyscmd82796
3187  Node: Sysval83210  Node: Sysval83749
3188  Node: Maketemp83614  Node: Maketemp84163
3189  Node: Miscellaneous84354  Node: Miscellaneous84913
3190  Node: Errprint84720  Node: Errprint85285
3191  Node: M4exit85708  Node: M4exit86287
3192  Node: Frozen files86490  Node: Frozen files87081
3193  Node: Compatibility91407  Node: Compatibility92004
3194  Node: Extensions92022  Node: Extensions92625
3195  Node: Incompatibilities94375  Node: Incompatibilities94988
3196  Node: Other Incompat94814  Node: Other Incompat95437
3197  Node: Concept index96974  Node: Concept index97607
3198  Node: Macro index103979  Node: Macro index107458
3199    
3200  End Tag Table  End Tag Table

Legend:
Removed from v.1.1.1.1.2.6  
changed lines
  Added in v.1.1.1.1.2.7

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26