1@ignore 2 3This file is part of AutoGen. 4AutoGen is free software. 5AutoGen is Copyright (C) 1992-2018 by Bruce Korb - all rights reserved 6 7AutoGen is free software: you can redistribute it and/or modify it 8under the terms of the GNU General Public License as published by the 9Free Software Foundation, either version 3 of the License, or 10(at your option) any later version. 11 12AutoGen is distributed in the hope that it will be useful, but 13WITHOUT ANY WARRANTY; without even the implied warranty of 14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 15See the GNU General Public License for more details. 16 17You should have received a copy of the GNU General Public License along 18with this program. If not, see <http://www.gnu.org/licenses/>. 19 20This file has the following md5sum: 21 2243b91e8ca915626ed3818ffb1b71248b COPYING.gplv3 23 24@end ignore 25@menu 26* Introduction:: AutoGen's Purpose 27* Definitions File:: AutoGen Definitions File 28* Template File:: AutoGen Template 29* Augmenting AutoGen:: Augmenting AutoGen Features 30* autogen Invocation:: Invoking AutoGen 31* Installation:: Configuring and Installing 32* AutoOpts:: Automated Option Processing 33* Add-Ons:: Add-on packages for AutoGen 34* Future:: Some ideas for the future. 35* Copying This Manual:: Copying This Manual 36* Concept Index:: General index 37* Function Index:: Function index 38@end menu 39 40@ignore 41* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 42@end ignore 43@page 44@node Introduction 45@chapter Introduction 46@cindex Introduction 47 48AutoGen is a tool designed for generating program files that contain 49repetitive text with varied substitutions. Its goal is to simplify the 50maintenance of programs that contain large amounts of repetitious text. 51This is especially valuable if there are several blocks of such text 52that must be kept synchronized in parallel tables. 53 54An obvious example is the problem of maintaining the code required for 55processing program options and configuration settings. Processing options 56requires a minimum of four different constructs be kept in proper order in 57different places in your program. You need at least: 58 59@enumerate 60@item 61The flag character in the flag string, 62@item 63code to process the flag when it is encountered, 64@item 65a global state variable or two, and 66@item 67a line in the usage text. 68@end enumerate 69 70@noindent 71You will need more things besides this if you choose to implement long option 72names, configuration (rc/ini) file processing, environment variable settings 73and keep all the documentation for these up to date. This can be done 74mechanically; with the proper templates and this program. In fact, it has 75already been done and AutoGen itself uses it@: @xref{AutoOpts}. For a simple 76example of Automated Option processing, @xref{Quick Start}. For a full list 77of the Automated Option features, @xref{Features}. Be forewarned, though, the 78feature list is ridiculously extensive. 79 80@menu 81* Generalities:: The Purpose of AutoGen 82* Example Usage:: A Simple Example 83* csh/zsh caveat:: csh/zsh caveat 84* Testimonial:: A User's Perspective 85@end menu 86 87@c === SECTION MARKER 88 89@node Generalities 90@section The Purpose of AutoGen 91 92The idea of this program is to have a text file, a template if 93you will, that contains the general text of the desired output file. 94That file includes substitution expressions and sections of text that are 95replicated under the control of separate definition files. 96 97@cindex design goals 98 99AutoGen was designed with the following features: 100 101@enumerate 102@item 103The definitions are completely separate from the template. By completely 104isolating the definitions from the template it greatly increases the 105flexibility of the template implementation. A secondary goal is that a 106template user only needs to specify those data that are necessary to describe 107his application of a template. 108 109@item 110Each datum in the definitions is named. Thus, the definitions can be 111rearranged, augmented and become obsolete without it being necessary to 112go back and clean up older definition files. Reduce incompatibilities! 113 114@item 115Every definition name defines an array of values, even when there is 116only one entry. These arrays of values are used to control the 117replication of sections of the template. 118 119@item 120There are named collections of definitions. They form a nested hierarchy. 121Associated values are collected and associated with a group name. 122These associated data are used collectively in sets of substitutions. 123 124@item 125The template has special markers to indicate where substitutions are 126required, much like the @code{$@{VAR@}} construct in a shell @code{here doc}. 127These markers are not fixed strings. They are specified at the start of 128each template. Template designers know best what fits into their 129syntax and can avoid marker conflicts. 130 131We did this because it is burdensome and difficult to avoid conflicts 132using either M4 tokenization or C preprocessor substitution rules. It 133also makes it easier to specify expressions that transform the value. 134Of course, our expressions are less cryptic than the shell methods. 135 136@item 137These same markers are used, in conjunction with enclosed keywords, to 138indicate sections of text that are to be skipped and for sections of 139text that are to be repeated. This is a major improvement over using C 140preprocessing macros. With the C preprocessor, you have no way of 141selecting output text because it is an @i{un}varying, mechanical 142substitution process. 143 144@item 145Finally, we supply methods for carefully controlling the output. 146Sometimes, it is just simply easier and clearer to compute some text or 147a value in one context when its application needs to be later. So, 148functions are available for saving text or values for later use. 149@end enumerate 150 151@c === SECTION MARKER 152 153@node Example Usage 154@section A Simple Example 155@cindex example, simple AutoGen 156 157This is just one simple example that shows a few basic features. 158If you are interested, you also may run "make check" with the 159@code{VERBOSE} environment variable set and see a number of other 160examples in the @file{agen5/test} directory. 161 162Assume you have an enumeration of names and you wish to associate some 163string with each name. Assume also, for the sake of this example, 164that it is either too complex or too large to maintain easily by hand. 165We will start by writing an abbreviated version of what the result 166is supposed to be. We will use that to construct our output templates. 167 168@noindent 169In a header file, @file{list.h}, you define the enumeration 170and the global array containing the associated strings: 171 172@example 173typedef enum @{ 174 IDX_ALPHA, 175 IDX_BETA, 176 IDX_OMEGA @} list_enum; 177 178extern char const* az_name_list[ 3 ]; 179@end example 180 181@noindent 182Then you also have @file{list.c} that defines the actual strings: 183 184@example 185#include "list.h" 186char const* az_name_list[] = @{ 187 "some alpha stuff", 188 "more beta stuff", 189 "final omega stuff" @}; 190@end example 191 192@noindent 193First, we will define the information that is unique for each enumeration 194name/string pair. This would be placed in a file named, @file{list.def}, 195for example. 196 197@example 198autogen definitions list; 199list = @{ list_element = alpha; 200 list_info = "some alpha stuff"; @}; 201list = @{ list_info = "more beta stuff"; 202 list_element = beta; @}; 203list = @{ list_element = omega; 204 list_info = "final omega stuff"; @}; 205@end example 206 207The @code{autogen definitions list;} entry defines the file as an AutoGen 208definition file that uses a template named @code{list}. That is followed by 209three @code{list} entries that define the associations between the 210enumeration names and the strings. The order of the differently named 211elements inside of list is unimportant. They are reversed inside of the 212@code{beta} entry and the output is unaffected. 213 214Now, to actually create the output, we need a template or two that can be 215expanded into the files you want. In this program, we use a single template 216that is capable of multiple output files. The definitions above refer to a 217@file{list} template, so it would normally be named, @file{list.tpl}. 218 219It looks something like this. 220(For a full description, @xref{Template File}.) 221 222@example 223[+ AutoGen5 template h c +] 224[+ CASE (suffix) +][+ 225 == h +] 226typedef enum @{[+ 227 FOR list "," +] 228 IDX_[+ (string-upcase! (get "list_element")) +][+ 229 ENDFOR list +] @} list_enum; 230 231extern char const* az_name_list[ [+ (count "list") +] ]; 232[+ 233 234 == c +] 235#include "list.h" 236char const* az_name_list[] = @{[+ 237 FOR list "," +] 238 "[+list_info+]"[+ 239 ENDFOR list +] @};[+ 240 241ESAC +] 242@end example 243 244The @code{[+ AutoGen5 template h c +]} text tells AutoGen that this is 245an AutoGen version 5 template file; that it is to be processed twice; 246that the start macro marker is @code{[+}; and the end marker is 247@code{+]}. The template will be processed first with a suffix value of 248@code{h} and then with @code{c}. Normally, the suffix values are 249appended to the @file{base-name} to create the output file name. 250 251The @code{[+ == h +]} and @code{[+ == c +]} @code{CASE} selection clauses 252select different text for the two different passes. In this example, 253the output is nearly disjoint and could have been put in two separate 254templates. However, sometimes there are common sections and this is 255just an example. 256 257The @code{[+FOR list "," +]} and @code{[+ ENDFOR list +]} clauses delimit 258a block of text that will be repeated for every definition of @code{list}. 259Inside of that block, the definition name-value pairs that 260are members of each @code{list} are available for substitutions. 261 262The remainder of the macros are expressions. Some of these contain 263special expression functions that are dependent on AutoGen named values; 264others are simply Scheme expressions, the result of which will be 265inserted into the output text. Other expressions are names of AutoGen 266values. These values will be inserted into the output text. For example, 267@code{[+list_info+]} will result in the value associated with 268the name @code{list_info} being inserted between the double quotes and 269@code{(string-upcase! (get "list_element"))} will first "get" the value 270associated with the name @code{list_element}, then change the case of 271all the letters to upper case. The result will be inserted into the 272output document. 273 274If you have compiled AutoGen, you can copy out the template and definitions 275as described above and run @code{autogen list.def}. This will produce 276exactly the hypothesized desired output. 277 278One more point, too. Lets say you decided it was too much trouble to figure 279out how to use AutoGen, so you created this enumeration and string list with 280thousands of entries. Now, requirements have changed and it has become 281necessary to map a string containing the enumeration name into the enumeration 282number. With AutoGen, you just alter the template to emit the table of names. 283It will be guaranteed to be in the correct order, missing none of the entries. 284If you want to do that by hand, well, good luck. 285 286@c === SECTION MARKER 287 288@node csh/zsh caveat 289@section csh/zsh caveat 290 291AutoGen tries to use your normal shell so that you can supply shell code 292in a manner you are accustomed to using. If, however, you use csh or 293zsh, you cannot do this. Csh is sufficiently difficult to program that 294it is unsupported. Zsh, though largely programmable, also has some 295anomalies that make it incompatible with AutoGen usage. Therefore, when 296invoking AutoGen from these environments, you must be certain to set the 297SHELL environment variable to a Bourne-derived shell, e.g., sh, ksh or 298bash. 299 300Any shell you choose for your own scripts need to follow these basic 301requirements: 302 303@enumerate 304@item 305It handles @code{trap ":" $sig} without output to standard out. This is done 306when the server shell is first started. If your shell does not handle this, 307then it may be able to by loading functions from its start up files. 308@item 309At the beginning of each scriptlet, the command @code{\\cd $PWD} 310is inserted. This ensures that @code{cd} is not aliased to something 311peculiar and each scriptlet starts life in the execution directory. 312@item 313At the end of each scriptlet, the command @code{echo mumble} is 314appended. The program you use as a shell must emit the single 315argument @code{mumble} on a line by itself. 316@end enumerate 317 318@c === SECTION MARKER 319 320@node Testimonial 321@section A User's Perspective 322 323@format 324Alexandre wrote: 325> 326> I'd appreciate opinions from others about advantages/disadvantages of 327> each of these macro packages. 328@end format 329 330I am using AutoGen in my pet project, and find one of its best points to 331be that it separates the operational data from the implementation. 332 333Indulge me for a few paragraphs, and all will be revealed: 334In the manual, Bruce cites the example of maintaining command line flags 335inside the source code; traditionally spreading usage information, flag 336names, letters and processing across several functions (if not files). 337Investing the time in writing a sort of boiler plate (a template in 338AutoGen terminology) pays by moving all of the option details (usage, 339flags names etc.) into a well structured table (a definition file if you 340will), so that adding a new command line option becomes a simple matter 341of adding a set of details to the table. 342 343So far so good! Of course, now that there is a template, writing all of 344that tedious optargs processing and usage functions is no longer an 345issue. Creating a table of the options needed for the new project and 346running AutoGen generates all of the option processing code in C 347automatically from just the tabular data. AutoGen in fact already ships 348with such a template... AutoOpts. 349 350One final consequence of the good separation in the design of AutoGen is 351that it is retargetable to a greater extent. The 352egcs/gcc/fixinc/inclhack.def can equally be used (with different 353templates) to create a shell script (inclhack.sh) or a c program 354(fixincl.c). 355 356This is just the tip of the iceberg. AutoGen is far more powerful than 357these examples might indicate, and has many other varied uses. I am 358certain Bruce or I could supply you with many and varied examples, and I 359would heartily recommend that you try it for your project and see for 360yourself how it compares to m4. 361@cindex m4 362 363As an aside, I would be interested to see whether someone might be 364persuaded to rationalise autoconf with AutoGen in place of m4... Ben, 365are you listening? autoconf-3.0! `kay? =)O| 366 367@format 368Sincerely, 369 Gary V. Vaughan 370@end format 371 372@ignore 373* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 374@end ignore 375@page 376@node Definitions File 377@chapter Definitions File 378@cindex definitions file 379@cindex .def file 380 381This chapter describes the syntax and semantics of the AutoGen 382definition file. In order to instantiate a template, you normally must 383provide a definitions file that identifies itself and contains some 384value definitions. Consequently, we keep it very simple. For 385"advanced" users, there are preprocessing directives, sparse 386arrays, named indexes and comments that may be used as well. 387 388The definitions file is used to associate values with names. Every 389value is implicitly an array of values, even if there is only one value. 390Values may be either simple strings or compound collections of 391name-value pairs. An array may not contain both simple and compound 392members. Fundamentally, it is as simple as: 393 394@example 395prog-name = "autogen"; 396flag = @{ 397 name = templ_dirs; 398 value = L; 399 descrip = "Template search directory list"; 400@}; 401@end example 402 403For purposes of commenting and controlling the processing of the 404definitions, C-style comments and most C preprocessing directives are 405honored. The major exception is that the @code{#if} directive is 406ignored, along with all following text through the matching 407@code{#endif} directive. The C preprocessor is not actually invoked, so 408C macro substitution is @strong{not} performed. 409 410@menu 411* Identification:: The Identification Definition 412* Definitions:: Named Definitions 413* Index Assignments:: Assigning an Index to a Definition 414* Dynamic Text:: Dynamic Text 415* Directives:: Controlling What Gets Processed 416* Predefines:: Pre-defined Names 417* Comments:: Commenting Your Definitions 418* Example:: What it all looks like. 419* Full Syntax:: Finite State Machine Grammar 420* Alternate Definition:: Alternate Definition Forms 421@end menu 422 423@c === SECTION MARKER 424 425@node Identification 426@section The Identification Definition 427@cindex identification 428 429The first definition in this file is used to identify it as a 430AutoGen file. It consists of the two keywords, 431@samp{autogen} and @samp{definitions} followed by the default 432template name and a terminating semi-colon (@code{;}). That is: 433 434@example 435 AutoGen Definitions @var{template-name}; 436@end example 437 438@noindent 439Note that, other than the name @var{template-name}, the words 440@samp{AutoGen} and @samp{Definitions} are searched for without case 441sensitivity. Most lookups in this program are case insensitive. 442 443@noindent 444Also, if the input contains more identification definitions, 445they will be ignored. This is done so that you may include 446(@pxref{Directives}) other definition files without an identification 447conflict. 448 449@cindex template file 450 451@noindent 452AutoGen uses the name of the template to find the corresponding template 453file. It searches for the file in the following way, stopping when 454it finds the file: 455 456@enumerate 457@item 458It tries to open @file{./@var{template-name}}. If it fails, 459@item 460it tries @file{./@var{template-name}.tpl}. 461@item 462It searches for either of these files in the directories listed in the 463templ-dirs command line option. 464@end enumerate 465 466If AutoGen fails to find the template file in one of these places, 467it prints an error message and exits. 468 469@c === SECTION MARKER 470 471@node Definitions 472@section Named Definitions 473@cindex definitions 474 475A name is a sequence of characters beginning with an alphabetic character 476(@code{a} through @code{z}) followed by zero or more alpha-numeric 477characters and/or separator characters: hyphen (@code{-}), underscore 478(@code{_}) or carat (@code{^}). Names are case insensitive. 479 480Any name may have multiple values associated with it. Every name may be 481considered a sparse array of one or more elements. If there is more than 482one value, the values my be accessed by indexing the value with 483@code{[index]} or by iterating over them using the FOR (@pxref{FOR}) AutoGen 484macro on it, as described in the next chapter. Sparse arrays are specified 485by specifying an index when defining an entry 486(@pxref{Index Assignments,, Assigning an Index to a Definition}). 487 488There are two kinds of definitions, @samp{simple} and @samp{compound}. 489They are defined thus (@pxref{Full Syntax}): 490 491@example 492compound_name '=' '@{' definition-list '@}' ';' 493 494simple-name[2] '=' string ';' 495 496no^text^name ';' 497@end example 498 499@noindent 500@code{simple-name} has the third index (index number 2) defined here. 501@code{No^text^name} is a simple definition with a shorthand empty string 502value. The string values for definitions may be specified in any of 503several formation rules. 504 505@menu 506* def-list:: Definition List 507* double-quote-string:: Double Quote String 508* single-quote-string:: Single Quote String 509* simple-string:: An Unquoted String 510* shell-generated:: Shell Output String 511* scheme-generated:: Scheme Result String 512* here-string:: A Here String 513* concat-string:: Concatenated Strings 514@end menu 515 516@cindex simple definitions 517@cindex compound definitions 518 519@node def-list 520@subsection Definition List 521 522@code{definition-list} is a list of definitions that may or may not 523contain nested compound definitions. Any such definitions may 524@strong{only} be expanded within a @code{FOR} block iterating over the 525containing compound definition. @xref{FOR}. 526 527Here is, again, the example definitions from the previous chapter, 528with three additional name value pairs. Two with an empty value 529assigned (@var{first} and @var{last}), and a "global" @var{group_name}. 530 531@example 532autogen definitions list; 533group_name = example; 534list = @{ list_element = alpha; first; 535 list_info = "some alpha stuff"; @}; 536list = @{ list_info = "more beta stuff"; 537 list_element = beta; @}; 538list = @{ list_element = omega; last; 539 list_info = "final omega stuff"; @}; 540@end example 541 542@node double-quote-string 543@subsection Double Quote String 544 545@cindex string, double quote 546The string follows the C-style escaping, using the backslash to quote 547(escape) the following character(s). Certain letters are translated to 548various control codes (e.g. @code{\n}, @code{\f}, @code{\t}, etc.). 549@code{x} introduces a two character hex code. @code{0} (the digit zero) 550introduces a one to three character octal code (note: an octal byte followed 551by a digit must be represented with three octal digits, thus: @code{"\0001"} 552yielding a NUL byte followed by the ASCII digit 1). Any other character 553following the backslash escape is simply inserted, without error, into the 554string being formed. 555 556Like ANSI "C", a series of these strings, possibly intermixed with 557single quote strings, will be concatenated together. 558 559@node single-quote-string 560@subsection Single Quote String 561 562@cindex string, single quote 563This is similar to the shell single-quote string. However, escapes 564@code{\} are honored before another escape, single quotes @code{'} 565and hash characters @code{#}. This latter is done specifically 566to disambiguate lines starting with a hash character inside 567of a quoted string. In other words, 568 569@example 570fumble = ' 571#endif 572'; 573@end example 574 575could be misinterpreted by the definitions scanner, whereas 576this would not: 577 578@example 579fumble = ' 580\#endif 581'; 582@end example 583 584@* 585As with the double quote string, a series of these, even intermixed 586with double quote strings, will be concatenated together. 587 588@node simple-string 589@subsection An Unquoted String 590 591A simple string that does not contain white space @i{may} be left 592unquoted. The string must not contain any of the characters special to 593the definition text (i.e., @code{"}, @code{#}, @code{'}, @code{(}, 594@code{)}, @code{,}, @code{;}, @code{<}, @code{=}, @code{>}, @code{[}, 595@code{]}, @code{`}, @code{@{}, or @code{@}}). This list is subject to 596change, but it will never contain underscore (@code{_}), period 597(@code{.}), slash (@code{/}), colon (@code{:}), hyphen (@code{-}) or 598backslash (@code{\\}). Basically, if the string looks like it is a 599normal DOS or UNIX file or variable name, and it is not one of two 600keywords (@samp{autogen} or @samp{definitions}) then it is OK to not 601quote it, otherwise you should. 602 603@node shell-generated 604@subsection Shell Output String 605@cindex shell-generated string 606 607@cindex string, shell output 608This is assembled according to the same rules as the double quote string, 609except that there is no concatenation of strings and the resulting string is 610written to a shell server process. The definition takes on the value of 611the output string. 612 613NB@: The text is interpreted by a server shell. There may be left over 614state from previous server shell processing. This scriptlet may also leave 615state for subsequent processing. However, a @code{cd} to the original 616directory is always issued before the new command is issued. 617 618@node scheme-generated 619@subsection Scheme Result String 620 621A scheme result string must begin with an open parenthesis @code{(}. 622The scheme expression will be evaluated by Guile and the 623value will be the result. The AutoGen expression functions 624are @strong{dis}abled at this stage, so do not use them. 625 626@node here-string 627@subsection A Here String 628@cindex here-string 629 630A @samp{here string} is formed in much the same way as a shell here doc. It 631is denoted with two less than characters(@code{<<}) and, optionally, a hyphen. 632This is followed by optional horizontal white space and an ending 633marker-identifier. This marker must follow the syntax rules for identifiers. 634Unlike the shell version, however, you must not quote this marker. 635 636The resulting string will start with the first character on the next line and 637continue up to but not including the newline that precedes the line that 638begins with the marker token. The characters are copied directly into the 639result string. Mostly. 640 641If a hyphen follows the less than characters, then leading tabs will be 642stripped and the terminating marker will be recognized even if preceded by 643tabs. Also, if the first character on the line (after removing tabs) is a 644backslash and the next character is a tab or space, then the backslash will 645be removed as well. No other kind of processing is done on this string. 646 647Here are three examples: 648@example 649str1 = <<- STR_END 650 $quotes = " ' ` 651 STR_END; 652 653str2 = << STR_END 654 $quotes = " ' ` 655 STR_END; 656STR_END; 657 658str3 = <<- STR_END 659 \ $quotes = " ' ` 660 STR_END; 661@end example 662The first string contains no new line characters. 663The first character is the dollar sign, the last the back quote. 664 665The second string contains one new line character. The first character 666is the tab character preceding the dollar sign. The last character is 667the semicolon after the @code{STR_END}. That @code{STR_END} does not 668end the string because it is not at the beginning of the line. In the 669preceding case, the leading tab was stripped. 670 671The third string is almost identical to the first, except that the 672first character is a tab. That is, it exactly matches the first line 673of the second string. 674 675@node concat-string 676@subsection Concatenated Strings 677@cindex concat-string 678 679If single or double quote characters are used, 680then you also have the option, a la ANSI-C syntax, 681of implicitly concatenating a series of them together, 682with intervening white space ignored. 683 684NB@: You @strong{cannot} use directives to alter the string 685content. That is, 686 687@example 688str = "fumble" 689#ifdef LATER 690 "stumble" 691#endif 692 ; 693@end example 694 695@noindent 696will result in a syntax error. The preprocessing directives are not 697carried out by the C preprocessor. However, 698 699@example 700str = '"fumble\n" 701#ifdef LATER 702" stumble\n" 703#endif 704'; 705@end example 706 707@noindent 708@strong{Will} work. It will enclose the @samp{#ifdef LATER} 709and @samp{#endif} in the string. But it may also wreak 710havoc with the definition processing directives. The hash 711characters in the first column should be disambiguated with 712an escape @code{\} or join them with previous lines: 713@code{"fumble\n#ifdef LATER...}. 714 715@c === SECTION MARKER 716 717@node Index Assignments 718@section Assigning an Index to a Definition 719@cindex Definition Index 720 721In AutoGen, every name is implicitly an array of values. 722When assigning values, they are usually implicitly 723assigned to the next highest slot. They can also be 724specified explicitly: 725 726@example 727mumble[9] = stumble; 728mumble[0] = grumble; 729@end example 730 731@noindent 732If, subsequently, you assign a value to @code{mumble} without an 733index, its index will be @code{10}, not @code{1}. 734If indexes are specified, they must not cause conflicts. 735 736@code{#define}-d names may also be used for index values. 737This is equivalent to the above: 738 739@example 740#define FIRST 0 741#define LAST 9 742mumble[LAST] = stumble; 743mumble[FIRST] = grumble; 744@end example 745 746All values in a range do @strong{not} have to be filled in. 747If you leave gaps, then you will have a sparse array. This 748is fine (@pxref{FOR}). You have your choice of iterating 749over all the defined values, or iterating over a range 750of slots. This: 751 752@example 753[+ FOR mumble +][+ ENDFOR +] 754@end example 755 756@noindent 757iterates over all and only the defined entries, whereas this: 758 759@example 760[+ FOR mumble (for-by 1) +][+ ENDFOR +] 761@end example 762 763@noindent 764will iterate over all 10 "slots". Your template will 765likely have to contain something like this: 766 767@example 768[+ IF (exist? (sprintf "mumble[%d]" (for-index))) +] 769@end example 770 771@noindent 772or else "mumble" will have to be a compound value that, 773say, always contains a "grumble" value: 774 775@example 776[+ IF (exist? "grumble") +] 777@end example 778 779@c === SECTION MARKER 780 781@node Dynamic Text 782@section Dynamic Text 783@cindex Dynamic Definition Text 784 785There are several methods for including dynamic content inside a definitions 786file. Three of them are mentioned above (@ref{shell-generated} and 787@pxref{scheme-generated}) in the discussion of string formation rules. 788Another method uses the @code{#shell} processing directive. 789It will be discussed in the next section (@pxref{Directives}). 790Guile/Scheme may also be used to yield to create definitions. 791 792When the Scheme expression is preceded by a backslash and single 793quote, then the expression is expected to be an alist of 794names and values that will be used to create AutoGen definitions. 795 796@noindent 797This method can be be used as follows: 798 799@example 800\'( (name (value-expression)) 801 (name2 (another-expr)) ) 802@end example 803 804@noindent 805This is entirely equivalent to: 806 807@example 808name = (value-expression); 809name2 = (another-expr); 810@end example 811 812@noindent 813Under the covers, the expression gets handed off to a Guile function 814named @code{alist->autogen-def} in an expression that looks like this: 815 816@example 817(alist->autogen-def 818 ( (name (value-expression)) (name2 (another-expr)) ) ) 819@end example 820