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