* Makefile.am (EXTRA_DIST): Add "dejagnu" launcher script and

	contents of $(commands_DATA).
	(bin_SCRIPTS): Add "dejagnu" launcher script.
	(commandsdir): Installation directory for "dejagnu" subcommands is
	$(pkgdatadir)/commands.
	(commands_DATA): New, contains "commands/help.sh" as initial item.
	(TESTSUITE_FILES): Add testsuite for same.
	(DEJATOOL): Add "launcher" to list of tools to test.
	(dist_man_MANS): Add man pages for "dejagnu" and "dejagnu help".

	* doc/dejagnu.texi (Running other DejaGnu commands): New chapter.
	(Invoking dejagnu): New node for dejagnu(1) launcher script.
	(Invoking dejagnu help): New node.

	* doc/dejagnu.1: New man page.
	* doc/dejagnu-help.1: New man page.

	* dejagnu: New script.

	* commands/help.sh: New dejagnu subcommand for reading manpages.

	* testsuite/launcher.all/command.exp: New file.
	* testsuite/launcher.all/command/commands/bar-baz.awk: New file.
	* testsuite/launcher.all/command/commands/bar.awk: New file.
	* testsuite/launcher.all/command/commands/bar.sh: New file.
	* testsuite/launcher.all/command/commands/baz-quux.gawk: New file.
	* testsuite/launcher.all/command/commands/foo.sh: New file.
	* testsuite/launcher.all/command/commands/foo.tcl: New file.
	* testsuite/launcher.all/help.exp: New file.
	* testsuite/launcher.all/interp.exp: New file.
	* testsuite/launcher.all/verbose.exp: New file.
	* testsuite/lib/launcher.exp: New file.

Signed-off-by: Ben Elliston <bje@gnu.org>

3 files changed, 302 insertions, 3 deletions

diff --git a/doc/dejagnu-help.1 b/doc/dejagnu-help.1
new file mode 100644
index 0000000..110da92
--- /dev/null
+++ b/doc/dejagnu-help.1
@@ -0,0 +1,50 @@
+.\" Copyright (C), 2018  Free Software Foundation, Inc.
+.\" You may distribute this file under the terms of the GNU Free
+.\" Documentation License.
+.Dd December 19, 2018
+.Os GNU
+.Dt DEJAGNU-HELP 1 URM
+.Sh NAME
+.Nm dejagnu\ help
+.Nd display manual pages for DejaGnu auxiliary commands
+.Sh SYNOPSIS
+.Nm dejagnu\ help
+.Op Ar options...
+.Ao Ar command Ac
+.Sh DESCRIPTION
+The
+.Nm
+command displays long-form documentation for DejaGnu auxiliary commands.
+.Sh OPTIONS
+.Bl -tag -width ".Fl v , -verbose"
+.It Fl v , -verbose
+Emit additional output describing the operation of
+.Nm
+itself.
+.It Fl w , -path
+This option is simply passed on to
+.Nm man .
+.It Fl W
+This option is simply passed on to
+.Nm man .
+.El
+.Sh FILES
+The
+.Nm
+command checks for man pages in a
+.Pa doc/
+directory next to the
+.Pa commands/
+directory where this script is located.
+If the page is found there, a full file name is given to
+.Nm man .
+Otherwise, only the command name is given and the search described in
+.Xr man 1
+is performed.
+.Sh SEE ALSO
+.Xr man 1
+.Sh AUTHORS
+Jacob Bachmeyer
+.Sh BUGS
+Currently only supports man pages.
+.\"  LocalWords:  Dt URM Nm DejaGnu Ao Xr
diff --git a/doc/dejagnu.1 b/doc/dejagnu.1
new file mode 100644
index 0000000..5ece6c1
--- /dev/null
+++ b/doc/dejagnu.1
@@ -0,0 +1,141 @@
+.\" Copyright (C) 2018  Free Software Foundation, Inc.
+.\" You may distribute this file under the terms of the GNU Free
+.\" Documentation License.
+.Dd December 17, 2018
+.Os GNU
+.Dt DEJAGNU 1 URM
+.Sh NAME
+.Nm dejagnu
+.Nd DejaGnu auxiliary command launcher
+.Sh SYNOPSIS
+.Nm dejagnu
+.Ao Ar command Ac
+.Op Fl -help \*(Ba Ar options...
+.Nm
+.Fl -help
+.Nm
+.Fl -version
+.Sh DESCRIPTION
+The
+.Nm
+command finds a script that implements the requested
+.Ar command ,
+selects from multiple implementations if available
+according to a fixed internal list, and executes the command.
+.Sh OPTIONS
+.Bl -tag -width ".Fl -version"
+.It Fl -help
+Print a help message instead of running a command.
+If no command is given, prints brief usage for
+.Nm
+itself.
+.It Fl V , -version
+Print a version banner for the launcher itself including the version of DejaGnu.
+Any command given is ignored.
+.It Fl v , -verbose
+Emit additional output describing the operation of the
+.Nm
+launcher itself.
+This option is also passed on to the invoked command.
+.El
+.Pp
+All arguments after the command name are passed to the invoked command.
+.Sh ENVIRONMENT
+.Bl -tag -width ".Ev DEJAGNULIBS"
+.It Ev DEJAGNULIBS
+If set, the location of DejaGnu's library in the filesystem.
+The search described in
+.Sx FILES
+does not happen if
+.Ev DEJAGNULIBS
+is set.
+.It Ev AWK
+Full file name for an Awk interpreter that may or may not actually be GNU Awk.
+If not set,
+.Ev PATH
+will be searched for an
+.Nm awk
+program.
+If the Awk interpreter is actually GNU Awk, the
+.Fl -posix
+option will be given if an Awk implementation is used.
+.It Ev GAWK
+Full file name for GNU Awk.  If not set,
+.Ev PATH
+will be searched for a
+.Nm gawk
+program.
+.It Ev BASH
+Full file name for GNU Bash.  If not set,
+.Ev PATH
+will be searched for a
+.Nm bash
+program.
+Note that Bash itself sets this variable, even when run as
+.Nm sh ,
+even when running a script.
+.It Ev EXPECT
+Full file name for Expect, which is a Tcl interpreter with the Expect
+extension already loaded.  If not set,
+.Ev PATH
+will be searched for an
+.Nm expect
+program.  Note that the DejaGnu core is written in Expect, so this
+interpreter should always be available.
+.It Ev TCLSH
+Full file name for a Tcl interpreter.  If not set,
+.Ev PATH
+will be searched for a
+.Nm tclsh
+program.
+.El
+.Pp
+Note that GNU Awk is considered a superset of Awk and that Expect is
+considered a superset of Tcl, allowing the former to be used to run scripts
+written for the latter.
+This means that, while Awk programs will generally be run with GNU
+extensions disabled using the
+.Fl -posix
+option to GNU Awk, Tcl programs may be run with either
+.Nm tclsh
+or
+.Nm expect
+and should be written accordingly.
+.Sh FILES
+.Bl -tag -width ".Pa $DEJAGNULIBS/commands"
+.It Pa $DEJAGNULIBS/commands
+If
+.Ev DEJAGNULIBS
+is set, all command scripts are expected to be in this directory.
+.El
+Otherwise, the first directory that actually exists in the following list
+is used, where
+.Pa @bindir@
+represents the directory containing
+.Nm
+itself.
+.Bl -item -offset indent
+.It
+.Pa @bindir@/../share/dejagnu/commands
+.It
+.Pa @bindir@/../../share/dejagnu/commands
+.It
+.Pa /usr/share/dejagnu/commands
+.It
+.Pa /usr/local/share/dejagnu/commands
+.El
+.\" .Sh EXAMPLES
+.Sh SEE ALSO
+The full documentation for DejaGnu is maintained as a Texinfo manual.
+If the
+.Nm info
+program is properly installed at your site, the command
+.Li info dejagnu
+should give you access to the complete manual.
+.Sh AUTHORS
+.An "Jacob Bachmeyer"
+.Sh BUGS
+The command name must precede all other arguments due to limitations of the
+shell.
+.\"  LocalWords:  Dt URM Nm DejaGnu Ao DEJAGNULIBS DejaGnu's Sx awk posix tclsh
+.\"  LocalWords:  tcl superset bindir usr Texinfo
diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi
index 44c1b0b..e07a40a 100644
--- a/doc/dejagnu.texi
+++ b/doc/dejagnu.texi
@@ -50,6 +50,7 @@ Free Documentation License''.
 @menu
 * Introduction::
 * Running tests::
+* Running other DejaGnu commands::
 * Customizing DejaGnu::
 * Extending DejaGnu::
 * Unit testing::
@@ -75,6 +76,11 @@ Running tests
 * Running runtest: Runtest.
 * Output files: Output Files.
 
+Running other DejaGnu commands
+
+* Invoking dejagnu::            Command line options for the launcher itself.
+* Invoking dejagnu help::	Reading man pages for dejagnu subcommands.
+
 Customizing DejaGnu
 
 * Global config file::
@@ -421,7 +427,7 @@ tools you want to test; then, in each test directory, run @emph{make
 check} to build auxiliary programs required by some of the tests, and
 run the test suites.
 
-@node Running tests, Customizing DejaGnu, Introduction, Top
+@node Running tests, Running other DejaGnu commands, Introduction, Top
 @chapter Running tests
 
 There are two ways to execute a testsuite. The most common way is when
@@ -1008,7 +1014,109 @@ make the actions for fail-safe patterns produce messages starting with
 
 @end itemize
 
-@node Customizing DejaGnu, Extending DejaGnu, Running tests, Top
+@node Running other DejaGnu commands, Customizing DejaGnu, Running tests, Top
+@chapter Running other DejaGnu commands
+
+DejaGnu now features auxiliary commands not directly related to
+running tests, but somehow related to the broader purpose of testing.
+
+These commands are run via the @command{dejagnu} multiplex launcher,
+which locates an appropriate script and the required interpreter and
+then runs the requested command.
+
+@menu
+* Invoking dejagnu::            Command line options for the launcher itself.
+* Invoking dejagnu help::	Reading man pages for dejagnu subcommands.
+@end menu
+
+@node Invoking dejagnu, Invoking dejagnu help, Running other DejaGnu commands, Running other DejaGnu commands
+@section Invoking @command{dejagnu}
+@cindex dejagnu, invoking
+
+The @command{dejagnu} launcher is primarily designed to pass most
+options on to the scripts that it runs, but does process the
+@option{--help} and @option{--version} options entirely internally,
+while also recognizing the @option{--verbose} option.
+
+@example
+@command{dejagnu} <command> [options...]
+@command{dejagnu} --help
+@command{dejagnu} --version
+@end example
+
+Note that the command names may contain multiple words.  In this case,
+the command can be given as separate arguments to @command{dejagnu} or
+combined with dashes (@samp{-}); both forms are equivalent.
+
+All words of the command name must appear before any options.  The
+search for a command terminates when an option is found.
+
+Note that the first valid command found is used.  A longer command
+name can be shadowed by a shorter command name that happens to be a
+prefix of the longer name, if the command name is given as multiple
+arguments.  The equivalent form with the longer command name combined
+using dashes into a single argument will correctly refer to the
+otherwise shadowed command.
+
+The @command{dejagnu} launcher can also be run using symbolic links,
+provided that the shell places the name under which @command{dejagnu}
+was invoked in @code{$0}.  Any dash-separated words after ``dejagnu''
+in the name of such a link are taken to be the leading words of a
+command name.
+
+The @command{dejagnu} launcher supports alternate implementations
+depending upon available interpreters.
+
+Options for the @command{dejagnu} launcher itself cannot be
+abbreviated, since the launcher has no way to know which abbreviations
+are unique and which would be ambiguous to the invoked command.
+
+@table @asis
+
+@item @code{--help}
+Print a help message instead of running a command.
+
+@item @code{-V}, @code{--version}
+Print a version banner for the launcher itself including the
+version of DejaGnu.  Any command given is ignored.
+
+@item @code{-v}, @code{--verbose}
+Emit additional output describing the inner workings of the
+@command{dejagnu} launcher.  This option is also passed on to the
+invoked command.
+
+@end table
+
+All arguments after the command name are passed to the invoked command.
+
+@node Invoking dejagnu help,  , Invoking dejagnu, Running other DejaGnu commands
+@section Invoking @command{dejagnu help}
+@cindex dejagnu help, invoking
+
+The @command{dejagnu help} tool displays long-form documentation for
+DejaGnu auxiliary commands that are invoked using the
+@command{dejagnu} launcher.
+
+@example
+@command{dejagnu help} [options...] <command>
+@end example
+
+Again, command names may contain multiple words.  This command forms
+an operand by joining all words in the command name using dashes
+(@samp{-}) and prepending @samp{dejagnu-}.  This is then used as the
+name of a manual page and passed to the @command{man} command.
+
+If the manual page is in a particular directory relative to the script
+implementing this command, a full file name is produced, otherwise,
+@command{man} performs its normal search.
+
+The @option{--verbose} option causes additional output describing the
+inner workings of the @command{dejagnu help} command to be produced.
+
+The @option{--path}, @option{-w}, and @option{-W} options are passed
+to @command{man}.
+
+@node Customizing DejaGnu, Extending DejaGnu, Running other DejaGnu commands, Top
 @chapter Customizing DejaGnu
 @cindex customization
 
@@ -5502,4 +5610,4 @@ This makes @code{runtest} exit. Abbreviation: @kbd{q}.
 @bye
 
 @c  LocalWords:  subdirectory prepend prepended testsuite filename Expect's svn
-@c  LocalWords:  DejaGnu CVS RCS SCCS
+@c  LocalWords:  DejaGnu CVS RCS SCCS prepending subcommands