IC_BEGIN must be the very first command (besides IC_META_... commands) which is called in a configure.base file, and it must be called exactly once. It initializes many basic properties of the final configure script.
The version number can be either a single character sequence of the form "0.0.0" or a list of the form "0 0 0 extra", where extra is optional. In both cases, the substitution identifier "VERSION" will be created, in the latter case additionally "VERSION_MAJOR", "VERSION_MINOR", "VERSION_MICRO" and, if extra is given, "VERSION_EXTRA". (If your project needs more specific identifiers than just "VERSION...", have a look at the documentation of IC_SUBSTITUTE, behavior 16.)
behavior is the standard identifier substitution behavior; that is, what should happen when IC_SUBSTITUTE is used explicitly or implicitly without its optional "behavior" parameter.
IC_END must be the last command which is called in a configure.base file, and it must be called exactly once. It makes sure that everything's finished properly and writes the configure script file.
Makes sure that configure and configure.act are launched from the correct directory. file should be the relative path to a file in the package directory which is "characteristic" for the package. This command is optional, but it's highly recommended that you use it; otherwise the Makefile etc. might be created in the wrong directory (e.g. if a user is in a sub-directory and types "../configure" instead of "./configure") and users might flame you because they think that your software package doesn't work. :-)
Puts the code into the configure script. Keep in mind that you must escape single-quote characters ("'").
Puts the code into the config.h file. Keep in mind that you must escape single-quote characters ("'"). You shouldn't use this "low-level" command but instead use commands like IC_SUBSTITUTE or IC_OPTION_ENABLE if possible.
Adds the collector and compressor code to the configure script. This code will be executed when the script is called with the command-line option "--dist", which is only intended for the maintainers of a software package to build distribution archives. The collector code should create a directory with shell commands like
rm -rf dir
and then copy (collect) directories and files into that, and the compressor code should compress it to create distribution archives for upload to a server, distribution via CD etc. You might wonder why there are two different code blocks instead of only one; the reason becomes clear when you think of itchconfig's (coming) sub-configuration mechanism: at first the collector code will be executed, then the collectors of all relevant sub-configuration scripts, and finally the compressor code.
The optional parameter dir specifies some kind of "distribution base-directory"; it may only consist of lower-case letters. If you specify it, it will be added to the cleaning target "maintainer-clean" in the auto-generated Makefile and should be the same directory name which you use in the collector code. It is highly recommended that you use "dist" as the distribution base-directory name and that you only copy distribution-related stuff there.
The command-line option for running the code need not be a simple "--dist"; it can be any character sequence which begins with "--dist". The actual option will be stored in ic_dist_arg, so your code can create different kinds of distribution archives depending on that value. An example: you generally want to support four different kinds of distribution archives, say A, B, C, D (e.g. for .tar.gz, .zip or a minimal package, a large package with all files for all possible features, ...); currently you only need to create B and D; you could use the option "--distBD" and let your code do something like "case $ic_dist_arg in ... *B*) ... esac".
In (coming) sub-configuration configure.base files, dir must be left out (because the dir of the top-level configure.base file is used), and likewise the compressor because it makes only sense in the top-level configure.base file. For the collector code, ic_sub_fullpath will contain the relative path from the top-level directory of the package to the current directory; you can use this to calculate a path back "upwards" into the top-level directory and thus into the distribution base directory; of course you could also use something like "../../../dist" directly instead if the sub-directories won't ever be moved around during further development of the package.
Makes sure that only itchconfig version or newer can be used to process configure.base. Older versions will produce an error message.
Adds a comment of the form "Parts of this script are text" to the beginning of the configure script and to the output of "./configure --version". If text is something like "written by J. Random Hacker" or "Copyright (C) 200x foobar Inc.", you'll get a comment which might make sense. :-) This command is intended for configure.base files which contain non-trivial code in IC_EMIT_SH commands for which you want to be credited.
Adds a comment containing the text to the beginning of the configure script; any dollar and double-quote characters will be removed. This command makes easy integration with CVS and similar tools possible.