home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / gnu / m4-1.1-bin.lha / info / m4.info-1 (.txt) < prev    next >
GNU Info File  |  1994-02-24  |  50KB  |  1,095 lines
  1. This is Info file m4.info, produced by Makeinfo-1.47 from the input
  2. file m4.texinfo.
  3.    This file documents the GNU m4 utility.
  4.    Copyright (C) 1989, 1990, 1991, 1992, 1993 Free Software Foundation,
  5.    Permission is granted to make and distribute verbatim copies of this
  6. manual provided the copyright notice and this permission notice are
  7. preserved on all copies.
  8.    Permission is granted to copy and distribute modified versions of
  9. this manual under the conditions for verbatim copying, provided also
  10. that the entire resulting derived work is distributed under the terms
  11. of a permission notice identical to this one.
  12.    Permission is granted to copy and distribute translations of this
  13. manual into another language, under the above conditions for modified
  14. versions.
  15. File: m4.info,  Node: Top,  Next: Intro,  Prev: (dir),  Up: (dir)
  16.    This file documents GNU the `m4' simple macroprocessor, as of
  17. release 1.1.  It has been originally written by Rene Seindal, from
  18. Denmark.
  19. * Menu:
  20. * Intro::                       Introduction to m4
  21. * Manual::                      How to use this manual
  22. * Bugs::                        Reporting bugs in m4
  23. * Invoking m4::                 How to run the program
  24. * Syntax::                      Lexical and syntactic conventions
  25. * Macros::                      How to invoke macros
  26. * Definitions::                 How to define new macros
  27. * Conditionals::                Conditionals and loops
  28. * Debugging::                   How to debug macros and input
  29. * Input Control::               Input control
  30. * File Inclusion::              File inclusion
  31. * Diversions::                  Diverting and undiverting output
  32. * Text handling::               Macros for text handling
  33. * Arithmetic::                  Macros for doing arithmetic
  34. * Unix commands::               Macros for running Unix commands
  35. * Miscellaneous::               Miscellaneous built-in macros
  36. * Compatibility::               Compatibility with other versions of m4
  37. * Concept index::        Index for many concepts
  38. * Macro index::            Index for all m4 macros
  39.  -- The Detailed Node Listing --
  40. Lexical and syntactic conventions
  41. * Names::                       Macro names.
  42. * Quoted strings::              Quoting input to m4.
  43. * Other tokens::                Other kinds of input tokens.
  44. * Comments::                    Comments in m4 input.
  45. How to invoke macros
  46. * Invocation::                  Macro invocation
  47. * Macro Arguments::             Macro arguments.
  48. * Quoting Arguments::           On Quoting Arguments to macros.
  49. * Macro expansion::             Expanding macros.
  50. How to define new macros
  51. * Define::                      Defining a new macro
  52. * Arguments::                   Arguments to macros
  53. * Pseudo Arguments::            Pseudo arguments to macros
  54. * Undefine::                    Deleting a macro
  55. * Defn::                        Renaming macros
  56. * Pushdef::                     Temporarily redefining macros
  57. * Indir::                       Indirect call of macros
  58. * Builtin::                     Indirect call of built-ins
  59. Conditionals, loops and recursion
  60. * Ifdef::                       Testing if a macro is defined
  61. * Ifelse::                      If-else construct, or multibranch
  62. * Loops::                       Loops and recursion in m4
  63. How to debug macros and input
  64. * Dumpdef::                     Displaying macro definitions
  65. * Trace::                       Tracing macro calls
  66. * Debug Levels::                Controlling debugging output
  67. * Debug Output::                Saving debugging output
  68. Input control
  69. * Dnl::                         Deleting whitespace in input
  70. * Changequote::                 Changing the quote characters
  71. * Changecom::                   Changing the comment delimiters
  72. * M4wrap::                      Saving input until end of input
  73. File inclusion
  74. * Include::                     Including named files
  75. * Search Path::                 Searching for include files
  76. Diverting and undiverting output
  77. * Divert::                      Diverting output
  78. * Undivert::                    Undiverting output
  79. * Divnum::                      Diversion numbers
  80. * Cleardiv::                    Discarding diverted text
  81. Macros for text handling
  82. * Len::                         Calculating length of strings
  83. * Index::                       Searching for substrings
  84. * Regexp::                      Searching for regular expressions
  85. * Substr::                      Extracting substrings
  86. * Translit::                    Translating characters
  87. * Patsubst::                    Substituting text by regular expression
  88. * Format::                      Formatting strings (printf-like)
  89. Macros for doing arithmetic
  90. * Incr::                        Decrement and increment operators
  91. * Eval::                        Evaluating integer expressions
  92. Running Unix commands
  93. * Syscmd::                      Executing simple commands
  94. * Esyscmd::                     Reading the output of commands
  95. * Sysval::                      Exit codes
  96. * Maketemp::                    Making names for temporary files
  97. Miscellaneous built-in macros
  98. * Errprint::                    Printing error messages
  99. * M4exit::                      Exiting from m4
  100. Compatibility with other versions of `m4'
  101. * Extensions::                  Extensions in GNU m4
  102. * Incompatibilities::           Facilities in System V m4 not in GNU m4
  103. * Other Incompat::              Other incompatibilities
  104. File: m4.info,  Node: Intro,  Next: Manual,  Prev: Top,  Up: Top
  105. Introduction to `m4'
  106. ********************
  107.    `m4' is a macro processor, in the sense that in copies its input to
  108. the output, expanding macros as it goes.  Macros are either built-in or
  109. user-defined, and can take any number of arguments.  Besides just doing
  110. macro expansion, `m4' has built-in functions for including named files,
  111. running Unix commands, doing integer arithmetic, manipulating text in
  112. various ways, recursion, etc...
  113.    `m4' can be used either as a front-end to a compiler, or as a macro
  114. processor in its own right.
  115.    GNU `m4' is mostly compatible with the System V, Release 3 version,
  116. except for some minor differences.  *Note Compatibility:: for more
  117. details.
  118. File: m4.info,  Node: Manual,  Next: Bugs,  Prev: Intro,  Up: Top
  119. Using this manual
  120. *****************
  121.    This manual contains a number of examples of `m4' input and output,
  122. and a simple notation is used to distinguish input, output and error
  123. messages from `m4'.  Examples are set out from the normal text, and
  124. shown in a fixed width font, like this
  125.      This is an example of an example!
  126.    To distinguish input from output, all output from `m4' is prefixed
  127. by the string `=>', and all error messages by the string `error-->'. 
  128.      Example of input line
  129.      =>Output line from m4
  130.      error-->and an error message
  131.    As each of the predefined macros in `m4' is described, a prototype
  132. call of the macro will be shown, giving descriptive names to the
  133. arguments, e.g.,
  134.      regexp(STRING, REGEXP, opt REPLACEMENT)
  135.    All macro arguments in `m4' are strings, but some are given special
  136. interpretation, e.g., as numbers, filenames, regular expressions, etc.
  137.    The `opt' before the third argument shows that this argument is
  138. optional--if it is left out, it is taken to be the empty string.  An
  139. ellipsis (`...') last in the argument list indicates that any number of
  140. arguments may follow.
  141. File: m4.info,  Node: Bugs,  Next: Invoking m4,  Prev: Manual,  Up: Top
  142. Problems and bugs
  143. *****************
  144.    If you have problems with GNU `m4' or think you've found a bug,
  145. please report it.  Before reporting a bug, make sure you've actually
  146. found a real bug.  Carefully reread the documentation and see if it
  147. really says you can do what you're trying to do.  If it's not clear
  148. whether you should be able to do something or not, report that too; it's
  149. a bug in the documentation!
  150.    Before reporting a bug or trying to fix it yourself, try to isolate
  151. it to the smallest possible input file that reproduces the problem. 
  152. Then send us the input file and the exact results `m4' gave you.  Also
  153. say what you expected to occur; this will help us decide whether the
  154. problem was really in the documentation.
  155.    Once you've got a precise problem, send e-mail to (Internet)
  156. `bug-gnu-utils@prep.ai.mit.edu' or (UUC