docs: document AM_MISSING_PROG

Addresses automake bug#11793.

This macro has been present for a long time, and coreutils has been
relying on it despite no documentation, which argues that it is stable
enough to be worth documenting.

Furthermore, since we are hoping to change our preferred invocation
from 'missing --run program' to 'missing program' in a future version
of automake, we need a way for packages to consistently get the
preferred invocation form rather than open-coding a call to 'missing'.
In particular, the Autoconf manual would love to recommend this macro
when discussing how to integrate an autotest suite with automake.

* doc/automake.texi (Public Macros): Document AM_MISSING_PROG.

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

diff --git a/doc/automake.texi b/doc/automake.texi
index 059241d..20af53e 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -4062,6 +4062,16 @@ variable.  The default @var{compiler-search-list} is @samp{upcc upc}.
 This macro will abort @command{configure} if no Unified Parallel C
 compiler is found.
 
+@item AM_MISSING_PROG(@var{name}, @var{program})
+@acindex AM_MISSING_PROG
+@vindex MISSING
+Find a maintainer tool @var{program} and define the @var{name}
+environment variable with its location.  If @var{program} is not
+detected, then @var{name} will instead invoke the @command{missing}
+script, in order to give useful advice to the user about the missing
+maintainer tool.  @xref{maintainer-mode}, for more information on when
+the @command{missing} script is appropriate.
+
 @item AM_SILENT_RULES
 @acindex AM_SILENT_RULES
 Enable the machinery for less verbose build output (@pxref{Options}).