finish up all docs, except for the unimplemented .explain() method

CONTRIBUTING.rst

@@ -16,6 +16,9 @@ The build specifies C99 conformance, all compiler warnings turned on,
 and all warnings considered errors (compiler options ``-std=c99
 -Werror -Wall -Wextra``).
 
+The VMOD has been tested with both the gcc and clang compilers, and
+should always compile and test successfully with both of them.
+
 By default, ``CFLAGS`` is set to ``-g -O2``, so that symbols are
 included in the shared library, and optimization is at level
 ``O2``. To change or disable these options, set ``CFLAGS`` explicitly

INSTALL.rst

@@ -11,6 +11,9 @@ resources. This sequence will install the VMOD::
   > make check		# to run unit tests in src/tests/*.vtc
   > sudo make install
 
+``make check`` requires that the VMOD ``blobcode`` is installed
+(https://code.uplex.de/uplex-varnish/libvmod-blobcode).
+
 If you have installed Varnish in a non-standard directory, call
 ``autogen.sh`` and ``configure`` with the ``PKG_CONFIG_PATH``
 environment variable pointing to the appropriate path. For example,

README.rst

@@ -66,7 +66,7 @@ provided by Akamai Media Services. Applications of the VMOD include:
 
 This manual presupposes familiarity with the Akamai SecureHD
 service. For more information, see the documentation provided by
-Akamai (XXX: links).
+Akamai (see `Akamai documentation`_).
 
 The VMOD does not provide cryptographic code to generate HMACs, but it
 does provide the means to associate shared secrets with a policy,
@@ -92,7 +92,8 @@ a TTL, and possibly a shared secret used for authorization. For example::
       # Define a policy for token authorization lasting one hour,
       # and associate it with a shared secret.
       new token_policy
-      	  = hoailona.policy(TOKEN, 1h, blobcode.decode(encoded="secret"));
+      	  = hoailona.policy(TOKEN, 1h,
+	                    blobcode.decode(encoded="secret"));
   
       # Define a policy for open access (authorization not required)
       new open_policy = hoailona.policy(OPEN, 1h);
@@ -297,9 +298,9 @@ Examples::
   # Token authorization required, where authorization lasts 2 hours,
   # using the given shared secret, and setting the start offset to
   # 10 seconds before "now".
-  # (Note that in current versions of VCL, the negative integer for
-  # start_offset must be written as 0-10, because negative literals
-  # are not parsed correctly.)
+  # (Note that in Varnish 5.0.0, the negative integer for start_offset
+  # must be written as 0-10, because negative literals are not parsed
+  # correctly.)
   import blobcode;
   new token = hoailona.policy(type=TOKEN, ttl=2h, start_offset=0-10,
                               secret=blobcode.decode(HEX,
@@ -644,31 +645,72 @@ Example::
 
         std.log("Using VMOD hoailona version " + hoailona.version());
 
-ERRORS
-======
-
-...
-
 REQUIREMENTS
 ============
 
-This VMOD requires Varnish ...
+This VMOD requires Varnish since version 5.0.0.
 
 LIMITATIONS
 ===========
 
-...
+The VMOD uses Varnish workspace for the strings returned by the
+``hosts.token()`` method and for task-scoped data saved when the
+``hosts.policy()`` method is called. It also uses workspace during
+``vcl_init`` for temporary internal data structures needed while
+policy and hosts configurations are constructed. If the VMOD's methods
+fail with the message ``out of space`` in the Varnish log (with the
+log tag ``VCL_Error``), or if VCL initialization fails with such a
+message, then you need to increase one or both of the varnishd runtime
+parameters ``workspace_client`` and ``workspace_backend``.  The size
+of workspace during ``vcl_init`` is governed by ``workspace_client``.
+
+It appears to us that the Akamai documentation is not explicit about
+whether the ``...`` and ``*`` constructs in the path pattern syntax
+are required to match non-empty strings. Such a requirement would
+mean, for example, that ``/foo/*/bar`` and ``/foo/.../bar`` do not
+match ``/foo//bar``, that ``/foo/bar/...`` does not match
+``/foo/bar/`` (with no suffix), and that ``.../foo/bar`` does not
+match ``/foo/bar`` (with no prefix). All of their examples show these
+constructs matching non-empty strings, and it seems to us to be the
+intuitive interpretation. So the VMOD explicitly enforces this
+requirement.
 
 INSTALLATION
 ============
 
-See ``INSTALL``.
+See `INSTALL.rst <INSTALL.rst>`_ in the source repository.
 
 SEE ALSO
 ========
 
 * varnishd(1)
 * vcl(7)
+* source repository: https://code.uplex.de/uplex-varnish/libvmod-hoailona
+* VMOD blobcode: https://code.uplex.de/uplex-varnish/libvmod-blobcode
+* VMOD blobdigest: https://code.uplex.de/uplex-varnish/libvmod-blobdigest
+
+Akamai documentation
+--------------------
+
+Technical documentation about SecureHD token authorization appears to
+be available only to Akamai customers who have access to the Luna
+Control Center. This public document gives a non-technical overview:
+
+* https://www.akamai.com/jp/ja/multimedia/documents/product-brief/securehd-media-content-security-product-brief.pdf
+
+Users of the Luna Control Center can consult:
+
+* SecureHD Policy Editor User's Guide
+
+  * https://control.akamai.com/dl/customers/SPE/spe_ug.pdf
+
+* SecureHD Policy Editor online help
+
+  * https://control.akamai.com/dl/SPE/index.htm
+
+* Sanctioned token generator code (since code is the best documentation)
+
+  * https://control.akamai.com/dl/customers/SPE/EdgeAuth-latest.zip
 
 COPYRIGHT
 =========

src/vmod_hoailona.vcc

@@ -49,7 +49,7 @@ provided by Akamai Media Services. Applications of the VMOD include:
 
 This manual presupposes familiarity with the Akamai SecureHD
 service. For more information, see the documentation provided by
-Akamai (XXX: links).
+Akamai (see `Akamai documentation`_).
 
 The VMOD does not provide cryptographic code to generate HMACs, but it
 does provide the means to associate shared secrets with a policy,
@@ -75,7 +75,8 @@ a TTL, and possibly a shared secret used for authorization. For example::
       # Define a policy for token authorization lasting one hour,
       # and associate it with a shared secret.
       new token_policy
-      	  = hoailona.policy(TOKEN, 1h, blobcode.decode(encoded="secret"));
+      	  = hoailona.policy(TOKEN, 1h,
+	                    blobcode.decode(encoded="secret"));
   
       # Define a policy for open access (authorization not required)
       new open_policy = hoailona.policy(OPEN, 1h);
@@ -267,9 +268,9 @@ Examples::
   # Token authorization required, where authorization lasts 2 hours,
   # using the given shared secret, and setting the start offset to
   # 10 seconds before "now".
-  # (Note that in current versions of VCL, the negative integer for
-  # start_offset must be written as 0-10, because negative literals
-  # are not parsed correctly.)
+  # (Note that in Varnish 5.0.0, the negative integer for start_offset
+  # must be written as 0-10, because negative literals are not parsed
+  # correctly.)
   import blobcode;
   new token = hoailona.policy(type=TOKEN, ttl=2h, start_offset=0-10,
                               secret=blobcode.decode(HEX,
@@ -441,10 +442,10 @@ If more than one path pattern was assigned for the host, then it
 attempts to match the "most specific" patterns first. The general idea
 is: if, for example, the patterns ``/foo/.../bar`` and
 ``/foo/.../baz/bar`` were assigned for a matching host, and the
-``path`` to be matched is ``/foo/quux/baz/bar``, then
-``/foo/.../baz/bar`` will be matched and the policy type assigned for
-that pattern will be returned, even though ``/foo/.../bar`` would have
-also matched.
+``path`` to be matched is ``/foo/quux/baz/bar``, then the more
+specific pattern ``/foo/.../baz/bar`` will be matched and the policy
+type assigned for that pattern will be returned, even though
+``/foo/.../bar`` would have also matched.
 
 Formally, the "more specific" relation is defined as:
 
@@ -566,30 +567,71 @@ Example::
 
         std.log("Using VMOD hoailona version " + hoailona.version());
 
-ERRORS
-======
-
-...
-
 REQUIREMENTS
 ============
 
-This VMOD requires Varnish ...
+This VMOD requires Varnish since version 5.0.0.
 
 LIMITATIONS
 ===========
 
-...
+The VMOD uses Varnish workspace for the strings returned by the
+``hosts.token()`` method and for task-scoped data saved when the
+``hosts.policy()`` method is called. It also uses workspace during
+``vcl_init`` for temporary internal data structures needed while
+policy and hosts configurations are constructed. If the VMOD's methods
+fail with the message ``out of space`` in the Varnish log (with the
+log tag ``VCL_Error``), or if VCL initialization fails with such a
+message, then you need to increase one or both of the varnishd runtime
+parameters ``workspace_client`` and ``workspace_backend``.  The size
+of workspace during ``vcl_init`` is governed by ``workspace_client``.
+
+It appears to us that the Akamai documentation is not explicit about
+whether the ``...`` and ``*`` constructs in the path pattern syntax
+are required to match non-empty strings. Such a requirement would
+mean, for example, that ``/foo/*/bar`` and ``/foo/.../bar`` do not
+match ``/foo//bar``, that ``/foo/bar/...`` does not match
+``/foo/bar/`` (with no suffix), and that ``.../foo/bar`` does not
+match ``/foo/bar`` (with no prefix). All of their examples show these
+constructs matching non-empty strings, and it seems to us to be the
+intuitive interpretation. So the VMOD explicitly enforces this
+requirement.
 
 INSTALLATION
 ============
 
-See ``INSTALL``.
+See `INSTALL.rst <INSTALL.rst>`_ in the source repository.
 
 SEE ALSO
 ========
 
 * varnishd(1)
 * vcl(7)
+* source repository: https://code.uplex.de/uplex-varnish/libvmod-hoailona
+* VMOD blobcode: https://code.uplex.de/uplex-varnish/libvmod-blobcode
+* VMOD blobdigest: https://code.uplex.de/uplex-varnish/libvmod-blobdigest
+
+Akamai documentation
+--------------------
+
+Technical documentation about SecureHD token authorization appears to
+be available only to Akamai customers who have access to the Luna
+Control Center. This public document gives a non-technical overview:
+
+* https://www.akamai.com/jp/ja/multimedia/documents/product-brief/securehd-media-content-security-product-brief.pdf
+
+Users of the Luna Control Center can consult:
+
+* SecureHD Policy Editor User's Guide
+
+  * https://control.akamai.com/dl/customers/SPE/spe_ug.pdf
+
+* SecureHD Policy Editor online help
+
+  * https://control.akamai.com/dl/SPE/index.htm
+
+* Sanctioned token generator code (since code is the best documentation)
+
+  * https://control.akamai.com/dl/customers/SPE/EdgeAuth-latest.zip
 
 $Event event