Add documentation

* README: New file.
* bootstrap: Rename --copying to --license. Look for the license
file in the directory "copying" first.
* .gitignore: New file.
* license/gnu: New file.

* tmpl/Makefile.am: Use %[LICENSE] instead of %[COPYING]
* tmpl/configure.ac: Likewise.
* tmpl/src/Makefile.am: Likewise.
* tmpl/src/vmod.c: Likewise.
* tmpl/src/vmod.vcc: Likewise.
* tmpl/tests/Makefile.am: Likewise.
* tmpl/tests/testsuite.at: Likewise.

11 files changed, 296 insertions, 21 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..b2ea4fc
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+.emacs
+.emacs.*
+README.html
+*~
diff --git a/README b/README
new file mode 100644
index 0000000..9762ba4
--- /dev/null
+++ b/README
@@ -0,0 +1,247 @@
+#+TITLE: Varnish Cache module creator
+
+* Overview
+
+*Acvmod* is a framework for creating loadable modules for [[https://varnish-cache.org][Varnish
+Cache]] (_vmods_). It provides a set of macros and templates for configuring
+the module using GNU autotools and includes several auxiliary 
+tools for creating GNU-style ChangeLog, testsuite, etc.
+
+It is intended to be included as a git submodule to the _vmod_ project
+repository.
+
+* Creating new vmod
+
+The *bootstrap* tool is designed to facilitate the task of creating a
+new _vmod_ from the scratch. It takes a number of options supplying it
+with the additional data about the module, but in general, creating
+a new module is as simple as running:
+
+#+BEGIN_SRC shell-script
+  ./bootstrap -C $DIR $NAME
+#+END_SRC
+
+where =$NAME= is the module name and =$DIR= is the name of the
+directory where to create the skeleton for the module.
+
+Suppose you start to write a module named =vmod-new= (traditionally,
+vmod names are prefixed with =vmod_= or =vmod-=. *Acvmod* accepts the
+latter convention). Then, do the following:
+
+1. Clone the *acvmod*:
+  #+BEGIN_SRC shell-script
+    git clone git://git.gnu.org.ua/acvmod.git
+  #+END_SRC
+2. Run
+  #+BEGIN_SRC shell-script -r 
+    acvmod/bootstrap -C ~/src/vmod-new --git new
+  #+END_SRC
+
+The =--git= option instructs the tool that the module will be under 
+control of Git, so that *acvmod* will add itself as a submodule.
+
+This command will do the following:
+
+ * Create the directory =~/src/vmod-new=
+ * Copy entire *acvmod* package to this directory
+ * Initialize an empty Git repository in =~/src/vmod-new=
+ * Register *acvmod* as a Git submodule in this repository.
+ * Populate the directory with the files necessary to build a valid Varnish-Cache module
+ * Add these files to the repository index
+ * Run *autoreconf* to create the *configure* script and Makefiles.
+
+The =~/src/vmod-new= will now contain the following files:
+
+#+BEGIN_EXAMPLE
+COPYING
+Makefile.am
+acvmod/
+configure.ac
+m4/
+src/
+src/Makefile.am
+src/vmod_new.c
+src/vmod_new.vcc
+tests/
+tests/Makefile.am 
+tests/atlocal.in
+tests/testsuite.at
+#+END_EXAMPLE
+
+plus the Git infrastructure files and files created by autotools
+(=configure=, =Makefile.am='s, etc.)
+
+Note, that the new project created by *bootstrap* can already be compiled
+with the usual commands:
+
+  #+BEGIN_SRC shell-script
+    ./configure
+    make
+  #+END_SRC
+
+This will produce a module that you can import into your VCL script
+using the
+
+  #+BEGIN_SRC C
+    import new;
+  #+END_SRC
+
+statement. Of course, apart from it, the module won't do anything
+useful, so it's now time to change to =~src/vmod-new=, commit the
+changes and start hacking on the module source files =src/vmod_new.c=
+and =src/vmod_new.vcc=.
+
+** Bootstrap options
+
+The sample *bootstrap* invocation discussed above creates the module
+sources using the default settings. To customize them, a number of
+options are provided. You can always get a comprehensive summary of 
+these by running =bootstrap --help=. 
+
+*** Strictness level
+
+Automake [[https://www.gnu.org/software/automake/manual/html_node/Strictness.html][strictness level]] defines how stringently Automake checks
+standards conformance when creating =Makefile.in= files. Three
+mutually exclusive options are provided to control strictness:
+=--foreign=, =--gnu=, and =--gnits=. The default is =--foreign=.
+
+If =--gnu= is used, the following additional files will be created:
+=AUTHORS=, =NEWS=, =README=, and =ChangeLog=. The top-level
+=Makefile.am= file will include a rule for updating the latter from
+the git commit history.
+
+If =--gnits= is specified, the above files and the file =THANKS= will
+be created.
+
+*** Module description and URL
+
++ ~--version=N~ :: Sets module version number. Default value is *0.1*.
++ ~--description=TEXT~ :: One-line textual description of the module.
+     It will be included in the =$Module= line of the created *vcc*
+     file, and subsequently in the generated manpage. Default text 
+     is =No description yet=.
++ ~--url=URL~ :: URL of the project's web page. It is mentioned, among
+     others, in the generated =README= file.
++ ~--license=FILE~ :: Name of the file containing short license text,
+     which will be reproduced in heading comments of each created
+     source file. Unless _FILE_ begins with a directory separator
+     (=/=, or =./=. or =../=) it will be looked first in the
+     =acvmod/license= subdirectory, and if not found there, in the 
+     current working directory. 
+
+*** Personal information
+
+Some of the created files contain the author's personal information,
+such as email and real name. The *bootstrap* tool will do its best to 
+deduce this information from the system user database. Use the
+following two options if it guesses wrong:
+
+- ~--email=EMAIL~ :: Sets your email address. The default is your user
+     name, followed by the =@=-sign, followed by the hostname of the
+     machine on which *bootstrap* is run.
+- ~--real-name=TEXT~ :: Your real-world name. By default it is looked up 
+     in the _Gecos_ field of your =/etc/passwd= record.
+
+** Another example
+
+The following command was used to create initial set up of the 
+[[https://puszcza.gnu.org.ua/projects/vmod-dict][vmod-dict]] module:
+
+  #+BEGIN_SRC shell-script
+  bootstrap --gnu \
+            --git \
+            -C ~/src/vmod-dict \
+            --email gray@gnu.org \
+            --url http://ps.gnu.org.ua/software/vmod-dict \            
+            --description='Dictionary look-up for Varnish Cache' \
+            --license=gnu \
+            dict
+  #+END_SRC
+
+* The ~AM_VARNISHAPI~ macro
+
+The =AM_VARNISHAPI= macro is used in =configure.ac= to check whether
+the varnish API components (header files and libraries) are installed
+and are of sufficiently modern version. The macro is invoked with one
+optional argument - the oldest required version of the API:
+
+#+BEGIN_SRC autoconf
+ AM_VARNISHAPI([VERSION])
+#+END_SRC
+
+If =VERSION= argument is supplied, the macro checks if varnish API
+version is the same or newer than that version number.  Otherwise, if 
+package version string ends in -N.N.N, where N stands for a decimal
+digit, it checks if varnish API version is at least N.N.N. 
+If API is older, it emits error message and aborts. If the version is 
+newer, a warning message is emitted at the end of configure.
+
+The ~AM_VARNISHAPI~ macro sets the following configuration variables:
+
+- ~VMODDIR~  :: The path of the varnish module directory.
+- ~VARNISH_MAJOR~ :: Major number of the varnish API version.
+- ~VARNISH_MINOR~ :: Minor number of the varnish API version.
+- ~VARNISH_PATCH~ :: Patchlevel number of the varnish API version.
+- ~VARNISHD~ :: Full pathname of the varnishd binary.
+- ~VARNISHTEST~ :: Full pathname of the varnishtest binary.
+- ~VARNISHAPI_PKGDATADIR~ ::  Varnish API package data directory.
+- ~VARNISHAPI_VMODTOOL~ :: Absolute pathname of the vmodtool.py script. 
+
+* Module installation directory
+
+The produced =configure= script determines the location where 
+Varnish looks for loadable modules, and arranges for installing your
+module there. Most of the time that's what you and the end user would
+expect. However, there are cases when such behavior is undesirable. 
+
+For example, when packaging the module for distribution in binary
+form, the module should normally go to a temporary installation
+directory outside of the usual system-wide locations. To make it
+possible,  the generated =configure= provides the =--with-vmoddir= 
+option. Argument to this option defines the directory where to
+install the loadable module. 
+
+Another option is =--without-vmoddir=. If supplied, it instructs
+=configure= to follow the the standard practice of installing all files
+to subdirectories below the installation prefix (by default it is
+=/usr/local=; it can be changed via the =--prefix= command line option).
+This option is useful for testing the module. In fact, it is used by
+default when you run =make distcheck= to test and package your module.
+
+* The =top.am= file
+
+The =top.am= file is included in the generated top-level
+=Makefile.am=. This file defines a rule for creating =ChangeLog=
+file from the git log, adds to the distribution the =gencl= script,
+used by that rule, and the file =testsuite.inc=, which
+provides macros for use in testsuite. It also sets up the =distcheck=
+goal to use the =--without-vmoddir= option, described above.
+
+* Testsuite