diff options
Diffstat (limited to 'doc/m4.texi')
| -rw-r--r-- | doc/m4.texi | 154 |
1 files changed, 77 insertions, 77 deletions
diff --git a/doc/m4.texi b/doc/m4.texi index 77c3a5fe..8d40caee 100644 --- a/doc/m4.texi +++ b/doc/m4.texi @@ -3408,7 +3408,7 @@ by @var{separator}. While @code{joinall} always outputs a @end deffn Here are some examples of its usage, based on the implementation -@file{m4-@value{VERSION}/@/examples/@/join.m4} distributed in this +@file{m4-@value{VERSION}/@/doc/examples/@/join.m4} distributed in this package: @comment examples @@ -3442,7 +3442,7 @@ m4 programming idioms. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`join.m4')dnl @result{}divert(`-1') @result{}# join(sep, args) - join each non-empty ARG into a single @@ -3515,12 +3515,12 @@ quoting are added around each element. @end deffn An actual implementation of these three macros is distributed as -@file{m4-@value{VERSION}/@/examples/@/quote.m4} in this package. First, -let's examine their usage: +@file{m4-@value{VERSION}/@/doc/examples/@/quote.m4} in this package. +First, let's examine their usage: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`quote.m4') @result{} -quote-dquote-dquote_elt- @@ -3553,7 +3553,7 @@ resulting string. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`quote.m4')dnl @result{}divert(`-1') @result{}# quote(args) - convert args to single-quoted string @@ -3618,7 +3618,7 @@ It can, for example, be used for simple counting: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`forloop.m4') @result{} forloop(`i', `1', `8', `i ') @@ -3629,7 +3629,7 @@ For-loops can be nested, like: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`forloop.m4') @result{} forloop(`i', `1', `4', `forloop(`j', `1', `8', ` (i, j)') @@ -3653,11 +3653,11 @@ not finished, it increments the iterator (using the predefined macro @code{incr}, @pxref{Incr}), and recurses. Here is an actual implementation of @code{forloop}, distributed as -@file{m4-@value{VERSION}/@/examples/@/forloop.m4} in this package: +@file{m4-@value{VERSION}/@/doc/examples/@/forloop.m4} in this package: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`forloop.m4')dnl @result{}divert(`-1') @result{}# forloop(var, from, to, stmt) - simple version @@ -3699,12 +3699,12 @@ invocation is restored. As an example, this displays each word in a list inside of a sentence, using an implementation of @code{foreach} distributed as -@file{m4-@value{VERSION}/@/examples/@/foreach.m4}, and @code{foreachq} -in @file{m4-@value{VERSION}/@/examples/@/foreachq.m4}. +@file{m4-@value{VERSION}/@/doc/examples/@/foreach.m4}, and @code{foreachq} +in @file{m4-@value{VERSION}/@/doc/examples/@/foreachq.m4}. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`foreach.m4') @result{} foreach(`x', (foo, bar, foobar), `Word was: x @@ -3727,7 +3727,7 @@ to a helper macro. This example generates a shell case statement: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`foreach.m4') @result{} define(`_case', ` $1) @@ -3757,7 +3757,7 @@ through the original list. Here is a simple implementation of @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`foreach.m4')dnl @result{}divert(`-1') @result{}# foreach(x, (item_1, item_2, ..., item_n), stmt) @@ -3784,7 +3784,7 @@ rescan: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} define(`a', `1')define(`b', `2')define(`c', `3') @result{} include(`foreach.m4') @@ -3809,7 +3809,7 @@ Obviously, @code{foreachq} did a better job; here is its implementation: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`foreachq.m4')dnl @result{}include(`quote.m4')dnl @result{}divert(`-1') @@ -3836,7 +3836,7 @@ Invoking m4}). Additionally, this implementation does not expand @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`foreach.m4')include(`foreachq.m4') @result{} foreach(`name', `(`a', `b')', ` defn(`name')') @@ -3873,11 +3873,11 @@ few special macros, such as @code{defn}, which cannot be used as the @end deffn A sample implementation of these macros is distributed in the file -@file{m4-@value{VERSION}/@/examples/@/stack.m4}. +@file{m4-@value{VERSION}/@/doc/examples/@/stack.m4}. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`stack.m4') @result{} pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3') @@ -3913,7 +3913,7 @@ undefined during the algorithm. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`stack.m4')dnl @result{}divert(`-1') @result{}# stack_foreach(macro, action) @@ -4018,12 +4018,12 @@ obvious. The macro @code{stack_foreach} mentioned earlier is an example of a context that provides exactly one argument to a macro name. But coupled with currying, we can invoke @code{reverse} with two arguments for each definition of a macro stack. This example uses the file -@file{m4-@value{VERSION}/@/examples/@/curry.m4} included in the +@file{m4-@value{VERSION}/@/doc/examples/@/curry.m4} included in the distribution. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`curry.m4')include(`stack.m4') @result{} define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'', @@ -4048,7 +4048,7 @@ directly rather than going through @code{curry}. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`curry.m4')dnl @result{}divert(`-1') @result{}# curry(macro, args) @@ -4067,7 +4067,7 @@ versions: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`curry.m4') @result{} curry(`define', `mylen')(defn(`len')) @@ -4098,7 +4098,7 @@ M4 versions, or @pxref{Improved copy, , Answers}). @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`curry.m4')include(`stack.m4') @result{} define(`rename', `copy($@@)undefine(`$1')')dnl @@ -4681,14 +4681,14 @@ to macro tracing. @comment examples @comment options: -dip @example -$ @kbd{m4 -dip -I examples} +$ @kbd{m4 -dip -I doc/examples} @error{}m4debug: input read from 'stdin' define(`foo', `m4wrap(`wrapped text ')dnl') @result{} include(`incl.m4')dnl -@error{}m4debug: path search for 'incl.m4' found 'examples/incl.m4' -@error{}m4debug: input read from 'examples/incl.m4' +@error{}m4debug: path search for 'incl.m4' found 'doc/examples/incl.m4' +@error{}m4debug: input read from 'doc/examples/incl.m4' @result{}Include file start @result{}Include file end @error{}m4debug: input reverted to stdin, line 3 @@ -5922,12 +5922,12 @@ However, earlier versions had reverse ordering (LIFO---last in, first out), as this behavior is more like the semantics of the C function @code{atexit}. It is possible to emulate POSIX behavior even with older versions of GNU M4 by including the file -@file{m4-@value{VERSION}/@/examples/@/wrapfifo.m4} from the +@file{m4-@value{VERSION}/@/doc/examples/@/wrapfifo.m4} from the distribution: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`wrapfifo.m4')dnl @result{}dnl Redefine m4wrap to have FIFO semantics. @result{}define(`_m4wrap_level', `0')dnl @@ -5950,14 +5950,14 @@ m4wrap(`a`'m4wrap(`c It is likewise possible to emulate LIFO behavior without resorting to the GNU M4 extension of @code{builtin}, by including the file -@file{m4-@value{VERSION}/@/examples/@/wraplifo.m4} from the +@file{m4-@value{VERSION}/@/doc/examples/@/wraplifo.m4} from the distribution. (Unfortunately, both examples shown here share some subtle bugs. See if you can find and correct them; or @pxref{Improved m4wrap, , Answers}). @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`wraplifo.m4')dnl @result{}dnl Redefine m4wrap to have LIFO semantics. @result{}define(`_m4wrap_level', `0')dnl @@ -6086,14 +6086,14 @@ sinclude() This section uses the @option{--include} command-line option (or @option{-I}, @pxref{Preprocessor features, , Invoking m4}) to grab -files from the @file{m4-@value{VERSION}/@/examples} +files from the @file{m4-@value{VERSION}/@/doc/examples} directory shipped as part of the GNU @code{m4} package. The -file @file{m4-@value{VERSION}/@/examples/@/incl.m4} in the distribution +file @file{m4-@value{VERSION}/@/doc/examples/@/incl.m4} in the distribution contains the lines: @comment ignore @example -$ @kbd{cat examples/incl.m4} +$ @kbd{cat doc/examples/incl.m4} @result{}Include file start @result{}foo @result{}Include file end @@ -6105,7 +6105,7 @@ into the input stream. The contents of the file will be read by @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} define(`foo', `FOO') @result{} include(`incl.m4') @@ -6122,7 +6122,7 @@ of @file{incl.m4}: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} define(`bar', include(`incl.m4')) @result{} This is `bar': >>bar<< @@ -7371,11 +7371,11 @@ word to upper case and the remaining characters to lower case. @end deffn First, an example of their usage, using implementations distributed in -@file{m4-@value{VERSION}/@/examples/@/capitalize.m4}. +@file{m4-@value{VERSION}/@/doc/examples/@/capitalize.m4}. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`capitalize.m4') @result{} upcase(`GNUs not Unix') @@ -7395,7 +7395,7 @@ them; or @pxref{Improved capitalize, , Answers}). @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`capitalize.m4')dnl @result{}divert(`-1') @result{}# upcase(text) @@ -7502,7 +7502,7 @@ example shows how @code{format} can be used to produce tabular output. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`forloop.m4') @result{} forloop(`i', `1', `10', `format(`%6d squared is %10d @@ -8605,14 +8605,14 @@ This example reuses the file @file{incl.m4} mentioned earlier @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} define(`foo', ``$0' called at __file__:__line__') @result{} foo @result{}foo called at stdin:2 include(`incl.m4') @result{}Include file start -@result{}foo called at examples/incl.m4:2 +@result{}foo called at doc/examples/incl.m4:2 @result{}Include file end @result{} @end example @@ -8811,9 +8811,9 @@ mentioned earlier (@pxref{Include}): @comment examples @comment options: -s @example -$ @kbd{m4 --synclines -I examples} +$ @kbd{m4 --synclines -I doc/examples} include(`incl.m4') -@result{}#line 1 "examples/incl.m4" +@result{}#line 1 "doc/examples/incl.m4" @result{}Include file start @result{}foo @result{}Include file end @@ -9503,14 +9503,14 @@ The @code{forloop} macro (@pxref{Forloop}) as presented earlier can go into an infinite loop if given an iterator that is not parsed as a macro name. It does not do any sanity checking on its numeric bounds, and only permits decimal numbers for bounds. Here is an improved version, -shipped as @file{m4-@value{VERSION}/@/examples/@/forloop2.m4}; this +shipped as @file{m4-@value{VERSION}/@/doc/examples/@/forloop2.m4}; this version also optimizes overhead by calling four macros instead of six per iteration (excluding those in @var{text}), by not dereferencing the @var{iterator} in the helper @code{@w{_forloop}}. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} undivert(`forloop2.m4')dnl @result{}divert(`-1') @result{}# forloop(var, from, to, stmt) - improved version: @@ -9551,7 +9551,7 @@ to an infinite recursion loop in this example. @comment status: 1 @comment examples @example -$ @kbd{m4 -d -L 9 -I examples} +$ @kbd{m4 -d -L 9 -I doc/examples} define(`arg1', `$1')include(`forloop2.m4')include(`quote.m4') @result{} define(`double', `define(`$1'`2', @@ -9586,7 +9586,7 @@ to pass the current iterator value as a single argument. Coupled with with helper macros if the argument is needed in more than one place in the expansion, the output can be generated with three, rather than four, macros of overhead per iteration. Notice how the file -@file{m4-@value{VERSION}/@/examples/@/forloop3.m4} rearranges the +@file{m4-@value{VERSION}/@/doc/examples/@/forloop3.m4} rearranges the arguments of the helper @code{_forloop} to take two arguments that are placed around the current value. By splitting a balanced set of parantheses across multiple arguments, the helper macro can now be @@ -9594,7 +9594,7 @@ shared by @code{forloop} and the new @code{forloop_arg}. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`forloop3.m4') @result{} undivert(`forloop3.m4')dnl @@ -9645,7 +9645,7 @@ quadratic behavior of @code{foreachq}: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`foreachq.m4') @result{} traceon(`shift')debugmode(`aq') @@ -9683,11 +9683,11 @@ recursion use fewer arguments, rather than adding additional quoted uses of @code{shift}. By doing so, @code{m4} uses less memory, invokes fewer macros, is less likely to run into machine limits, and most importantly, performs faster. The fixed version of @code{foreachq} can -be found in @file{m4-@value{VERSION}/@/examples/@/foreachq2.m4}: +be found in @file{m4-@value{VERSION}/@/doc/examples/@/foreachq2.m4}: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`foreachq2.m4') @result{} undivert(`foreachq2.m4')dnl @@ -9735,11 +9735,11 @@ place, and by using the fixed-length @samp{$#} instead of an arbitrary length list as the key to end recursion. The result is an overhead of six macro invocations per loop (excluding any macros in @var{text}), instead of eight. This alternative approach is available as -@file{m4-@value{VERSION}/@/examples/@/foreach3.m4}: +@file{m4-@value{VERSION}/@/doc/examples/@/foreach3.m4}: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`foreachq3.m4') @result{} undivert(`foreachq3.m4')dnl @@ -9831,7 +9831,7 @@ not yet supported. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`foreachq4.m4') @result{} undivert(`foreachq4.m4')dnl @@ -9859,15 +9859,15 @@ foreachq(`x', ``1', `2', `3', `4'', `x @end example For yet another approach, the improved version of @code{foreach}, -available in @file{m4-@value{VERSION}/@/examples/@/foreach2.m4}, simply -overquotes the arguments to @code{@w{_foreach}} to begin with, using -@code{dquote_elt}. Then @code{@w{_foreach}} can just use +available in @file{m4-@value{VERSION}/@/doc/examples/@/foreach2.m4}, +simply overquotes the arguments to @code{@w{_foreach}} to begin with, +using @code{dquote_elt}. Then @code{@w{_foreach}} can just use @code{@w{_arg1}} to remove the extra layer of quoting that was added up front: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`foreach2.m4') @result{} undivert(`foreach2.m4')dnl @@ -9921,7 +9921,7 @@ one, although a leading space still remains. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`quote.m4')include(`foreachq2.m4') @result{} pushdef(`sep', `define(`sep', ``, '')') @@ -9954,7 +9954,7 @@ detrimental effects. @comment examples @example -$ @kbd{m4 -d -I examples} +$ @kbd{m4 -d -I doc/examples} include(`foreach2.m4') @result{} include(`foreachq2.m4') @@ -10074,11 +10074,11 @@ the other approach would give the same output, it does so at the expense of increasing the argument size on each iteration of @code{_stack_reverse_sep}, which results in quadratic instead of linear execution time. The improved stack walking macros are available in -@file{m4-@value{VERSION}/@/examples/@/stack_sep.m4}: +@file{m4-@value{VERSION}/@/doc/examples/@/stack_sep.m4}: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`stack_sep.m4') @result{} define(`copy', `ifdef(`$2', `errprint(`$2 already defined @@ -10130,7 +10130,7 @@ builtin preserves them for their intended use. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`wraplifo.m4') @result{} m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b') @@ -10157,13 +10157,13 @@ Finally, it is worth emulating the GNU M4 extension of saving all arguments to @code{m4wrap}, separated by a space, rather than saving just the first argument. This is done with the @code{join} macro documented previously (@pxref{Shift}). The improved LIFO example is -shipped as @file{m4-@value{VERSION}/@/examples/@/wraplifo2.m4}, and can -easily be converted to a FIFO solution by swapping the adjacent +shipped as @file{m4-@value{VERSION}/@/doc/examples/@/wraplifo2.m4}, and +can easily be converted to a FIFO solution by swapping the adjacent invocations of @code{joinall} and @code{defn}. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`wraplifo2.m4') @result{} undivert(`wraplifo2.m4')dnl @@ -10235,7 +10235,7 @@ double-quoted string: @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`capitalize.m4')dnl define(`active', `act1, ive')dnl define(`Active', `Act2, Ive')dnl @@ -10296,11 +10296,11 @@ string. In turn, that means the replacement text has unbalanced quotes, necessitating another round of @code{changequote}. In the fixed version below, (also shipped as -@file{m4-@value{VERSION}/@/examples/@/capitalize.m4}), @code{capitalize} -uses the alternate quotes of @samp{<<[} and @samp{]>>} (the longer -strings are chosen so as to be less likely to appear in the text being -converted). The helpers @code{_to_alt} and @code{_from_alt} merely -reduce the number of characters required to perform a +@file{m4-@value{VERSION}/@/doc/examples/@/capitalize.m4}), +@code{capitalize} uses the alternate quotes of @samp{<<[} and @samp{]>>} +(the longer strings are chosen so as to be less likely to appear in the +text being converted). The helpers @code{_to_alt} and @code{_from_alt} +merely reduce the number of characters required to perform a @code{changequote}, since the definition changes twice. The outermost pair means that @code{patsubst} and @code{_capitalize_alt} are invoked with alternate quoting; the innermost pair is used so that the third @@ -10312,7 +10312,7 @@ scheme in effect. @comment examples @example -$ @kbd{m4 -I examples} +$ @kbd{m4 -I doc/examples} include(`capitalize2.m4')dnl define(`active', `act1, ive')dnl define(`Active', `Act2, Ive')dnl @@ -10398,7 +10398,7 @@ restrictions, covered later (@pxref{Copying This Manual}). This appendix covers the license for copying this manual. Note that some of the longer examples in this manual are also distributed in the -directory @file{m4-@value{VERSION}/@/examples/}, where a more +directory @file{m4-@value{VERSION}/@/doc/examples/}, where a more permissive license is in effect when copying just the examples. @menu |