docs: document recent changes to AM_PROG_VALAC

* doc/automake.texi (Vala Support): Here.  This is a follow-up to
recent commit 'v1.12.4-20-gdf202a3', "vala: add action arguments,
for when no proper vala compiler is found".

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>

1 files changed, 16 insertions, 11 deletions

diff --git a/doc/automake.texi b/doc/automake.texi
index 914c1e843..b3ee47f6c 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -6876,28 +6876,33 @@ foo_SOURCES = foo.vala bar.vala zardoc.c
 @end example
 
 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
-compiled into C code by the Vala compiler. The generated @file{.c} files are
-distributed. The end user does not need to have a Vala compiler installed.
+compiled into C code by the Vala compiler. The generated @file{.c} files
+are distributed. The end user does not need to have a Vala compiler installed.
 
 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
 that will locate the Vala compiler and optionally check its version
 number.
 
-@defmac AM_PROG_VALAC (@ovar{minimum-version})
-Try to find a Vala compiler in @env{PATH}. If it is found, the variable
-@code{VALAC} is set. Optionally a minimum release number of the compiler
-can be requested:
-
-@example
-AM_PROG_VALAC([0.7.0])
-@end example
+@defmac AM_PROG_VALAC (@ovar{minimum-version}, @ovar{action-if-found},
+  @ovar{action-if-not-found})
+Search for a Vala compiler in @env{PATH}.  If it is found, the variable
+@code{VALAC} is set to point to it (see below for more details).  This
+macro takes three optional arguments.  The first argument, if present,
+is the minimum version of the Vala compiler required to compile this
+package.  If a compiler is found and satisfies @var{minimum-version},
+then @var{action-if-found} is run (this defaults to do nothing).
+Otherwise, @var{action-if-not-found} is run.  If @var{action-if-not-found}
+is not specified, the default value is to print a warning in case no
+compiler is found, and to abort the configure script (with status 77)
+if a too-old version of the compiler is found.
 @end defmac
 
 There are a few variables that are used when compiling Vala sources:
 
 @vtable @code
 @item VALAC
-Path to the Vala compiler.
+Absolute path to the Vala compiler, or @samp{:} if no suitable compiler
+could be found.
 
 @item VALAFLAGS
 Additional arguments for the Vala compiler.