import from redhat cvsfrom-devoorigin/redhatredhat

11 files changed, 11981 insertions, 0 deletions

diff --git a/doc/.cvsignore b/doc/.cvsignore
new file mode 100644
index 0000000..7abff1d
--- /dev/null
+++ b/doc/.cvsignore
@@ -0,0 +1,2 @@
+Makefile
+config.status
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..9521a40
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,47 @@
+## Process this file with automake to generate Makefile.in
+
+AUTOMAKE_OPTIONS = cygnus
+
+info_TEXINFOS = dejagnu.texi
+
+TARGETS = overview.rtf overview.html overview.dvi overview.ps
+
+docs: $(TARGETS)
+
+%.ps: %.dvi
+	dvips -o $@ $<
+
+%.pdf: %.sgml
+	db2pdf $<
+
+%.dvi: %.sgml
+	db2dvi $<
+
+%.rtf: %.sgml
+	db2rtf -o $@ $<
+
+%.gif: %.fig
+	convert -transparency white $< $@ # .fig -> .gif
+
+%.epsi: %.eps
+	ps2epsi $<                                     # .eps -> .epsi
+
+%.eps: %.fig
+	fig2dev -L ps -m 0.7 -p dummy $< > $@          # .fig -> .eps/portrait
+
+%.html: %.sgml
+	db2html $<
+
+# now for some extra dependencies that the automatic rules will not
+# catch:
+
+overview.pdf overview.ps overview.dvi overview.rtf overview.html: overview.sgml ref.sgml user.sgml
+
+clean:
+	rm -f $(TARGETS)
+
+# install-data-local: overview.pdf overview.html
+#	$(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html
+#	$(INSTALL_DATA) overview/*.html $(DESTDIR)$(pkgdatadir)/html
+#	$(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps
+#	$(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf
diff --git a/doc/Makefile.in b/doc/Makefile.in
new file mode 100644
index 0000000..31d809b
--- /dev/null
+++ b/doc/Makefile.in
@@ -0,0 +1,338 @@
+# Makefile.in generated automatically by automake 1.4 from Makefile.am
+
+# Copyright (C) 1994, 1995-8, 1999 Free Software Foundation, Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+
+SHELL = @SHELL@
+
+srcdir = @srcdir@
+top_srcdir = @top_srcdir@
+VPATH = @srcdir@
+prefix = @prefix@
+exec_prefix = @exec_prefix@
+
+bindir = @bindir@
+sbindir = @sbindir@
+libexecdir = @libexecdir@
+datadir = @datadir@
+sysconfdir = @sysconfdir@
+sharedstatedir = @sharedstatedir@
+localstatedir = @localstatedir@
+libdir = @libdir@
+infodir = @infodir@
+mandir = @mandir@
+includedir = @includedir@
+oldincludedir = /usr/include
+
+DESTDIR =
+
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+
+top_builddir = ..
+
+ACLOCAL = @ACLOCAL@
+AUTOCONF = @AUTOCONF@
+AUTOMAKE = @AUTOMAKE@
+AUTOHEADER = @AUTOHEADER@
+
+INSTALL = @INSTALL@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@ $(AM_INSTALL_PROGRAM_FLAGS)
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+transform = @program_transform_name@
+
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+BOARDS = @BOARDS@
+CC = @CC@
+CONFIG = @CONFIG@
+EXEEXT = @EXEEXT@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+PACKAGE = @PACKAGE@
+VERSION = @VERSION@
+
+AUTOMAKE_OPTIONS = cygnus
+
+info_TEXINFOS = dejagnu.texi
+
+TARGETS = overview.rtf overview.html overview.dvi overview.ps
+mkinstalldirs = $(SHELL) $(top_srcdir)/../mkinstalldirs
+CONFIG_CLEAN_FILES = 
+TEXI2DVI = `if test -f $(top_srcdir)/../texinfo/util/texi2dvi; then echo $(top_srcdir)/../texinfo/util/texi2dvi; else echo texi2dvi; fi`
+TEXINFO_TEX = $(top_srcdir)/../texinfo/texinfo.tex
+INFO_DEPS = dejagnu.info
+DVIS = dejagnu.dvi
+TEXINFOS = dejagnu.texi
+DIST_COMMON =  README Makefile.am Makefile.in configure configure.in
+
+
+DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST)
+
+TAR = gtar
+GZIP_ENV = --best
+all: all-redirect
+.SUFFIXES:
+.SUFFIXES: .dvi .info .ps .texi .texinfo .txi
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4) 
+	cd $(top_srcdir) && $(AUTOMAKE) --cygnus doc/Makefile
+
+Makefile: $(srcdir)/Makefile.in  $(top_builddir)/config.status
+	cd $(top_builddir) \
+	  && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status
+
+
+dejagnu.info: dejagnu.texi
+dejagnu.dvi: dejagnu.texi
+
+
+DVIPS = dvips
+
+.texi.info:
+	@rm -f $@ $@-[0-9] $@-[0-9][0-9]
+	$(MAKEINFO) -I $(srcdir) $<
+
+.texi.dvi:
+	TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \
+	  MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
+
+.texi:
+	@rm -f $@ $@-[0-9] $@-[0-9][0-9]
+	$(MAKEINFO) -I $(srcdir) $<
+
+.texinfo.info:
+	@rm -f $@ $@-[0-9] $@-[0-9][0-9]
+	$(MAKEINFO) -I $(srcdir) $<
+
+.texinfo:
+	@rm -f $@ $@-[0-9] $@-[0-9][0-9]
+	$(MAKEINFO) -I $(srcdir) $<
+
+.texinfo.dvi:
+	TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \
+	  MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
+
+.txi.info:
+	@rm -f $@ $@-[0-9] $@-[0-9][0-9]
+	$(MAKEINFO) -I $(srcdir) $<
+
+.txi.dvi:
+	TEXINPUTS=$(top_srcdir)/../texinfo/texinfo.tex:$$TEXINPUTS \
+	  MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $<
+
+.txi:
+	@rm -f $@ $@-[0-9] $@-[0-9][0-9]
+	$(MAKEINFO) -I $(srcdir) $<
+.dvi.ps:
+	$(DVIPS) $< -o $@
+
+install-info-am: $(INFO_DEPS)
+	@$(NORMAL_INSTALL)
+	$(mkinstalldirs) $(DESTDIR)$(infodir)
+	@list='$(INFO_DEPS)'; \
+	for file in $$list; do \
+	  if test -f $$file; then d=.; else d=$(srcdir); fi; \
+	  for ifile in `cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \
+	    if test -f $$d/$$ifile; then \
+	      echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \
+	      $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \
+	    else : ; fi; \
+	  done; \
+	done
+	@$(POST_INSTALL)
+	@if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \
+	  list='$(INFO_DEPS)'; \
+	  for file in $$list; do \
+	    echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\
+	    install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\
+	  done; \
+	else : ; fi
+
+uninstall-info:
+	$(PRE_UNINSTALL)
+	@if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \
+	  ii=yes; \
+	else ii=; fi; \
+	list='$(INFO_DEPS)'; \
+	for file in $$list; do \
+	  test -z "$ii" \
+	    || install-info --info-dir=$(DESTDIR)$(infodir) --remove $$file; \
+	done
+	@$(NORMAL_UNINSTALL)
+	list='$(INFO_DEPS)'; \
+	for file in $$list; do \
+	  (cd $(DESTDIR)$(infodir) && rm -f $$file $$file-[0-9] $$file-[0-9][0-9]); \
+	done
+
+dist-info: $(INFO_DEPS)
+	list='$(INFO_DEPS)'; \
+	for base in $$list; do \
+	  if test -f $$base; then d=.; else d=$(srcdir); fi; \
+	  for file in `cd $$d && eval echo $$base*`; do \
+	    test -f $(distdir)/$$file \
+	    || ln $$d/$$file $(distdir)/$$file 2> /dev/null \
+	    || cp -p $$d/$$file $(distdir)/$$file; \
+	  done; \
+	done
+
+mostlyclean-aminfo:
+	-rm -f dejagnu.aux dejagnu.cp dejagnu.cps dejagnu.dvi dejagnu.fn \
+	  dejagnu.fns dejagnu.ky dejagnu.kys dejagnu.ps dejagnu.log \
+	  dejagnu.pg dejagnu.toc dejagnu.tp dejagnu.tps dejagnu.vr \
+	  dejagnu.vrs dejagnu.op dejagnu.tr dejagnu.cv dejagnu.cn
+
+clean-aminfo:
+
+distclean-aminfo:
+
+maintainer-clean-aminfo:
+	for i in $(INFO_DEPS); do \
+	  rm -f $$i; \
+	  if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \
+	    rm -f $$i-[0-9]*; \
+	  fi; \
+	done
+clean-info: mostlyclean-aminfo
+tags: TAGS
+TAGS:
+
+
+distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir)
+
+subdir = doc
+
+distdir: $(DISTFILES)
+	@for file in $(DISTFILES); do \
+	  if test -f $$file; then d=.; else d=$(srcdir); fi; \
+	  if test -d $$d/$$file; then \
+	    cp -pr $$d/$$file $(distdir)/$$file; \
+	  else \
+	    test -f $(distdir)/$$file \
+	    || ln $$d/$$file $(distdir)/$$file 2> /dev/null \
+	    || cp -p $$d/$$file $(distdir)/$$file || :; \
+	  fi; \
+	done
+	$(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-info
+info-am: $(INFO_DEPS)
+info: info-am
+dvi-am: $(DVIS)
+dvi: dvi-am
+check-am:
+check: check-am
+installcheck-am:
+installcheck: installcheck-am
+install-info-am: 
+install-info: install-info-am
+install-exec-am:
+install-exec: install-exec-am
+
+install-data-am:
+install-data: install-data-am
+
+install-am: all-am
+	@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+install: install-am
+uninstall-am:
+uninstall: uninstall-am
+all-am: Makefile
+all-redirect: all-am
+install-strip:
+	$(MAKE) $(AM_MAKEFLAGS) AM_INSTALL_PROGRAM_FLAGS=-s install
+installdirs:
+
+
+mostlyclean-generic:
+
+clean-generic:
+
+distclean-generic:
+	-rm -f Makefile $(CONFIG_CLEAN_FILES)
+	-rm -f config.cache config.log stamp-h stamp-h[0-9]*
+
+maintainer-clean-generic:
+mostlyclean-am:  mostlyclean-aminfo mostlyclean-generic
+
+mostlyclean: mostlyclean-am
+
+clean-am:  clean-aminfo clean-generic mostlyclean-am
+
+clean: clean-am
+
+distclean-am:  distclean-aminfo distclean-generic clean-am
+
+distclean: distclean-am
+
+maintainer-clean-am:  maintainer-clean-aminfo maintainer-clean-generic \
+		distclean-am
+	@echo "This command is intended for maintainers to use;"
+	@echo "it deletes files that may require special tools to rebuild."
+
+maintainer-clean: maintainer-clean-am
+
+.PHONY: install-info-am uninstall-info mostlyclean-aminfo \
+distclean-aminfo clean-aminfo maintainer-clean-aminfo tags distdir \
+info-am info dvi-am dvi check check-am installcheck-am installcheck \
+install-info-am install-info install-exec-am install-exec \
+install-data-am install-data install-am install uninstall-am uninstall \
+all-redirect all-am all installdirs mostlyclean-generic \
+distclean-generic clean-generic maintainer-clean-generic clean \
+mostlyclean distclean maintainer-clean
+
+
+docs: $(TARGETS)
+
+%.ps: %.dvi
+	dvips -o $@ $<
+
+%.pdf: %.sgml
+	db2pdf $<
+
+%.dvi: %.sgml
+	db2dvi $<
+
+%.rtf: %.sgml
+	db2rtf -o $@ $<
+
+%.gif: %.fig
+	convert -transparency white $< $@ # .fig -> .gif
+
+%.epsi: %.eps
+	ps2epsi $<                                     # .eps -> .epsi
+
+%.eps: %.fig
+	fig2dev -L ps -m 0.7 -p dummy $< > $@          # .fig -> .eps/portrait
+
+%.html: %.sgml
+	db2html $<
+
+# now for some extra dependencies that the automatic rules will not
+# catch:
+
+overview.pdf overview.ps overview.dvi overview.rtf overview.html: overview.sgml ref.sgml user.sgml
+
+clean:
+	rm -f $(TARGETS)
+
+# install-data-local: overview.pdf overview.html
+#	$(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/html
+#	$(INSTALL_DATA) overview/*.html $(DESTDIR)$(pkgdatadir)/html
+#	$(INSTALL_DATA) overview.ps $(DESTDIR)$(pkgdatadir)/dejagnu.ps
+#	$(INSTALL_DATA) overview.pdf $(DESTDIR)$(pkgdatadir)/dejagnu.pdf
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/doc/README b/doc/README
new file mode 100644
index 0000000..fc8ae45
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,2 @@
+One can obtain the Free DocBook Tools for Linux and NT at
+http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html
diff --git a/doc/configure b/doc/configure
new file mode 100755
index 0000000..638b3bf
--- /dev/null
+++ b/doc/configure
@@ -0,0 +1,860 @@
+#! /bin/sh
+
+# Guess values for system-dependent variables and create Makefiles.
+# Generated automatically using autoconf version 2.12.1 
+# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc.
+#
+# This configure script is free software; the Free Software Foundation
+# gives unlimited permission to copy, distribute and modify it.
+
+# Defaults:
+ac_help=
+ac_default_prefix=/usr/local
+# Any additions from configure.in:
+
+# Initialize some variables set by options.
+# The variables have the same names as the options, with
+# dashes changed to underlines.
+build=NONE
+cache_file=./config.cache
+exec_prefix=NONE
+host=NONE
+no_create=
+nonopt=NONE
+no_recursion=
+prefix=NONE
+program_prefix=NONE
+program_suffix=NONE
+program_transform_name=s,x,x,
+silent=
+site=
+srcdir=
+target=NONE
+verbose=
+x_includes=NONE
+x_libraries=NONE
+bindir='${exec_prefix}/bin'
+sbindir='${exec_prefix}/sbin'
+libexecdir='${exec_prefix}/libexec'
+datadir='${prefix}/share'
+sysconfdir='${prefix}/etc'
+sharedstatedir='${prefix}/com'
+localstatedir='${prefix}/var'
+libdir='${exec_prefix}/lib'
+includedir='${prefix}/include'
+oldincludedir='/usr/include'
+infodir='${prefix}/info'
+mandir='${prefix}/man'
+
+# Initialize some other variables.
+subdirs=
+MFLAGS= MAKEFLAGS=
+SHELL=${CONFIG_SHELL-/bin/sh}
+# Maximum number of lines to put in a shell here document.
+ac_max_here_lines=12
+
+ac_prev=
+for ac_option
+do
+
+  # If the previous option needs an argument, assign it.
+  if test -n "$ac_prev"; then
+    eval "$ac_prev=\$ac_option"
+    ac_prev=
+    continue
+  fi
+
+  case "$ac_option" in
+  -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
+  *) ac_optarg= ;;
+  esac
+
+  # Accept the important Cygnus configure options, so we can diagnose typos.
+
+  case "$ac_option" in
+
+  -bindir | --bindir | --bindi | --bind | --bin | --bi)
+    ac_prev=bindir ;;
+  -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*)
+    bindir="$ac_optarg" ;;
+
+  -build | --build | --buil | --bui | --bu)
+    ac_prev=build ;;
+  -build=* | --build=* | --buil=* | --bui=* | --bu=*)
+    build="$ac_optarg" ;;
+
+  -cache-file | --cache-file | --cache-fil | --cache-fi \
+  | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c)
+    ac_prev=cache_file ;;
+  -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \
+  | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*)
+    cache_file="$ac_optarg" ;;
+
+  -datadir | --datadir | --datadi | --datad | --data | --dat | --da)
+    ac_prev=datadir ;;
+  -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \
+  | --da=*)
+    datadir="$ac_optarg" ;;
+
+  -disable-* | --disable-*)
+    ac_feature=`echo $ac_option|sed -e 's/-*disable-//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then
+      { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
+    fi
+    ac_feature=`echo $ac_feature| sed 's/-/_/g'`
+    eval "enable_${ac_feature}=no" ;;
+
+  -enable-* | --enable-*)
+    ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then
+      { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
+    fi
+    ac_feature=`echo $ac_feature| sed 's/-/_/g'`
+    case "$ac_option" in
+      *=*) ;;
+      *) ac_optarg=yes ;;
+    esac
+    eval "enable_${ac_feature}='$ac_optarg'" ;;
+
+  -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \
+  | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \
+  | --exec | --exe | --ex)
+    ac_prev=exec_prefix ;;
+  -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \
+  | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \
+  | --exec=* | --exe=* | --ex=*)
+    exec_prefix="$ac_optarg" ;;
+
+  -gas | --gas | --ga | --g)
+    # Obsolete; use --with-gas.
+    with_gas=yes ;;
+
+  -help | --help | --hel | --he)
+    # Omit some internal or obsolete options to make the list less imposing.
+    # This message is too long to be a string in the A/UX 3.1 sh.
+    cat << EOF
+Usage: configure [options] [host]
+Options: [defaults in brackets after descriptions]
+Configuration:
+  --cache-file=FILE       cache test results in FILE
+  --help                  print this message
+  --no-create             do not create output files
+  --quiet, --silent       do not print \`checking...' messages
+  --version               print the version of autoconf that created configure
+Directory and file names:
+  --prefix=PREFIX         install architecture-independent files in PREFIX
+                          [$ac_default_prefix]
+  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
+                          [same as prefix]
+  --bindir=DIR            user executables in DIR [EPREFIX/bin]
+  --sbindir=DIR           system admin executables in DIR [EPREFIX/sbin]
+  --libexecdir=DIR        program executables in DIR [EPREFIX/libexec]
+  --datadir=DIR           read-only architecture-independent data in DIR
+                          [PREFIX/share]
+  --sysconfdir=DIR        read-only single-machine data in DIR [PREFIX/etc]
+  --sharedstatedir=DIR    modifiable architecture-independent data in DIR
+                          [PREFIX/com]
+  --localstatedir=DIR     modifiable single-machine data in DIR [PREFIX/var]
+  --libdir=DIR            object code libraries in DIR [EPREFIX/lib]
+  --includedir=DIR        C header files in DIR [PREFIX/include]
+  --oldincludedir=DIR     C header files for non-gcc in DIR [/usr/include]
+  --infodir=DIR           info documentation in DIR [PREFIX/info]
+  --mandir=DIR            man documentation in DIR [PREFIX/man]
+  --srcdir=DIR            find the sources in DIR [configure dir or ..]
+  --program-prefix=PREFIX prepend PREFIX to installed program names
+  --program-suffix=SUFFIX append SUFFIX to installed program names
+  --program-transform-name=PROGRAM
+                          run sed PROGRAM on installed program names
+EOF
+    cat << EOF
+Host type:
+  --build=BUILD           configure for building on BUILD [BUILD=HOST]
+  --host=HOST             configure for HOST [guessed]
+  --target=TARGET         configure for TARGET [TARGET=HOST]
+Features and packages:
+  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
+  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
+  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
+  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
+  --x-includes=DIR        X include files are in DIR
+  --x-libraries=DIR       X library files are in DIR
+EOF
+    if test -n "$ac_help"; then
+      echo "--enable and --with options recognized:$ac_help"
+    fi
+    exit 0 ;;
+
+  -host | --host | --hos | --ho)
+    ac_prev=host ;;
+  -host=* | --host=* | --hos=* | --ho=*)
+    host="$ac_optarg" ;;
+
+  -includedir | --includedir | --includedi | --included | --include \
+  | --includ | --inclu | --incl | --inc)
+    ac_prev=includedir ;;
+  -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \
+  | --includ=* | --inclu=* | --incl=* | --inc=*)
+    includedir="$ac_optarg" ;;
+
+  -infodir | --infodir | --infodi | --infod | --info | --inf)
+    ac_prev=infodir ;;
+  -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*)
+    infodir="$ac_optarg" ;;
+
+  -libdir | --libdir | --libdi | --libd)
+    ac_prev=libdir ;;
+  -libdir=* | --libdir=* | --libdi=* | --libd=*)
+    libdir="$ac_optarg" ;;
+
+  -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \
+  | --libexe | --libex | --libe)
+    ac_prev=libexecdir ;;
+  -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \
+  | --libexe=* | --libex=* | --libe=*)
+    libexecdir="$ac_optarg" ;;
+
+  -localstatedir | --localstatedir | --localstatedi | --localstated \
+  | --localstate | --localstat | --localsta | --localst \
+  | --locals | --local | --loca | --loc | --lo)
+    ac_prev=localstatedir ;;
+  -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \
+  | --localstate=* | --localstat=* | --localsta=* | --localst=* \
+  | --locals=* | --local=* | --loca=* | --loc=* | --lo=*)
+    localstatedir="$ac_optarg" ;;
+
+  -mandir | --mandir | --mandi | --mand | --man | --ma | --m)
+    ac_prev=mandir ;;
+  -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*)
+    mandir="$ac_optarg" ;;
+
+  -nfp | --nfp | --nf)
+    # Obsolete; use --without-fp.
+    with_fp=no ;;
+
+  -no-create | --no-create | --no-creat | --no-crea | --no-cre \
+  | --no-cr | --no-c)
+    no_create=yes ;;
+
+  -no-recursion | --no-recursion | --no-recursio | --no-recursi \
+  | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r)
+    no_recursion=yes ;;
+
+  -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \
+  | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \
+  | --oldin | --oldi | --old | --ol | --o)
+    ac_prev=oldincludedir ;;
+  -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \
+  | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \
+  | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*)
+    oldincludedir="$ac_optarg" ;;
+
+  -prefix | --prefix | --prefi | --pref | --pre | --pr | --p)
+    ac_prev=prefix ;;
+  -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*)
+    prefix="$ac_optarg" ;;
+
+  -program-prefix | --program-prefix | --program-prefi | --program-pref \
+  | --program-pre | --program-pr | --program-p)
+    ac_prev=program_prefix ;;
+  -program-prefix=* | --program-prefix=* | --program-prefi=* \
+  | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*)
+    program_prefix="$ac_optarg" ;;
+
+  -program-suffix | --program-suffix | --program-suffi | --program-suff \
+  | --program-suf | --program-su | --program-s)
+    ac_prev=program_suffix ;;
+  -program-suffix=* | --program-suffix=* | --program-suffi=* \
+  | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*)
+    program_suffix="$ac_optarg" ;;
+
+  -program-transform-name | --program-transform-name \
+  | --program-transform-nam | --program-transform-na \
+  | --program-transform-n | --program-transform- \
+  | --program-transform | --program-transfor \
+  | --program-transfo | --program-transf \
+  | --program-trans | --program-tran \
+  | --progr-tra | --program-tr | --program-t)
+    ac_prev=program_transform_name ;;
+  -program-transform-name=* | --program-transform-name=* \
+  | --program-transform-nam=* | --program-transform-na=* \
+  | --program-transform-n=* | --program-transform-=* \
+  | --program-transform=* | --program-transfor=* \
+  | --program-transfo=* | --program-transf=* \
+  | --program-trans=* | --program-tran=* \
+  | --progr-tra=* | --program-tr=* | --program-t=*)
+    program_transform_name="$ac_optarg" ;;
+
+  -q | -quiet | --quiet | --quie | --qui | --qu | --q \
+  | -silent | --silent | --silen | --sile | --sil)
+    silent=yes ;;
+
+  -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb)
+    ac_prev=sbindir ;;
+  -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \
+  | --sbi=* | --sb=*)
+    sbindir="$ac_optarg" ;;
+
+  -sharedstatedir | --sharedstatedir | --sharedstatedi \
+  | --sharedstated | --sharedstate | --sharedstat | --sharedsta \
+  | --sharedst | --shareds | --shared | --share | --shar \
+  | --sha | --sh)
+    ac_prev=sharedstatedir ;;
+  -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \
+  | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \
+  | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \
+  | --sha=* | --sh=*)
+    sharedstatedir="$ac_optarg" ;;
+
+  -site | --site | --sit)
+    ac_prev=site ;;
+  -site=* | --site=* | --sit=*)
+    site="$ac_optarg" ;;
+
+  -srcdir | --srcdir | --srcdi | --srcd | --src | --sr)
+    ac_prev=srcdir ;;
+  -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*)
+    srcdir="$ac_optarg" ;;
+
+  -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \
+  | --syscon | --sysco | --sysc | --sys | --sy)
+    ac_prev=sysconfdir ;;
+  -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \
+  | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*)
+    sysconfdir="$ac_optarg" ;;
+
+  -target | --target | --targe | --targ | --tar | --ta | --t)
+    ac_prev=target ;;
+  -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*)
+    target="$ac_optarg" ;;
+
+  -v | -verbose | --verbose | --verbos | --verbo | --verb)
+    verbose=yes ;;
+
+  -version | --version | --versio | --versi | --vers)
+    echo "configure generated by autoconf version 2.12.1"
+    exit 0 ;;
+
+  -with-* | --with-*)
+    ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then
+      { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
+    fi
+    ac_package=`echo $ac_package| sed 's/-/_/g'`
+    case "$ac_option" in
+      *=*) ;;
+      *) ac_optarg=yes ;;
+    esac
+    eval "with_${ac_package}='$ac_optarg'" ;;
+
+  -without-* | --without-*)
+    ac_package=`echo $ac_option|sed -e 's/-*without-//'`
+    # Reject names that are not valid shell variable names.
+    if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then
+      { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
+    fi
+    ac_package=`echo $ac_package| sed 's/-/_/g'`
+    eval "with_${ac_package}=no" ;;
+
+  --x)
+    # Obsolete; use --with-x.
+    with_x=yes ;;
+
+  -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \
+  | --x-incl | --x-inc | --x-in | --x-i)
+    ac_prev=x_includes ;;
+  -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \
+  | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*)
+    x_includes="$ac_optarg" ;;
+
+  -x-libraries | --x-libraries | --x-librarie | --x-librari \
+  | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l)
+    ac_prev=x_libraries ;;
+  -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \
+  | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*)
+    x_libraries="$ac_optarg" ;;
+
+  -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; }
+    ;;
+
+  *)
+    if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then
+      echo "configure: warning: $ac_option: invalid host type" 1>&2
+    fi
+    if test "x$nonopt" != xNONE; then
+      { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; }
+    fi
+    nonopt="$ac_option"
+    ;;
+
+  esac
+done
+
+if test -n "$ac_prev"; then
+  { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; }
+fi
+
+trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
+
+# File descriptor usage:
+# 0 standard input
+# 1 file creation
+# 2 errors and warnings
+# 3 some systems may open it to /dev/tty
+# 4 used on the Kubota Titan
+# 6 checking for... messages and results
+# 5 compiler messages saved in config.log
+if test "$silent" = yes; then
+  exec 6>/dev/null
+else
+  exec 6>&1
+fi
+exec 5>./config.log
+
+echo "\
+This file contains any messages produced by compilers while
+running configure, to aid debugging if configure makes a mistake.
+" 1>&5
+
+# Strip out --no-create and --no-recursion so they do not pile up.
+# Also quote any args containing shell metacharacters.
+ac_configure_args=
+for ac_arg
+do
+  case "$ac_arg" in
+  -no-create | --no-create | --no-creat | --no-crea | --no-cre \
+  | --no-cr | --no-c) ;;
+  -no-recursion | --no-recursion | --no-recursio | --no-recursi \
+  | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;;
+  *" "*|*"	"*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*)
+  ac_configure_args="$ac_configure_args '$ac_arg'" ;;
+  *) ac_configure_args="$ac_configure_args $ac_arg" ;;
+  esac
+done
+
+# NLS nuisances.
+# Only set these to C if already set.  These must not be set unconditionally
+# because not all systems understand e.g. LANG=C (notably SCO).
+# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'!
+# Non-C LC_CTYPE values break the ctype check.
+if test "${LANG+set}"   = set; then LANG=C;   export LANG;   fi
+if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi
+if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi
+if test "${LC_CTYPE+set}"    = set; then LC_CTYPE=C;    export LC_CTYPE;    fi
+
+# confdefs.h avoids OS command line length limits that DEFS can exceed.
+rm -rf conftest* confdefs.h
+# AIX cpp loses on an empty file, so make sure it contains at least a newline.
+echo > confdefs.h
+
+# A filename unique to this package, relative to the directory that
+# configure is in, which we can look for to find out if srcdir is correct.
+ac_unique_file=dejagnu.texi
+
+# Find the source files, if location was not specified.
+if test -z "$srcdir"; then
+  ac_srcdir_defaulted=yes
+  # Try the directory containing this script, then its parent.
+  ac_prog=$0
+  ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'`
+  test "x$ac_confdir" = "x$ac_prog" && ac_confdir=.
+  srcdir=$ac_confdir
+  if test ! -r $srcdir/$ac_unique_file; then
+    srcdir=..
+  fi
+else
+  ac_srcdir_defaulted=no
+fi
+if test ! -r $srcdir/$ac_unique_file; then
+  if test "$ac_srcdir_defaulted" = yes; then
+    { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; }
+  else
+    { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; }
+  fi
+fi
+srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'`
+
+# Prefer explicitly selected file to automatically selected ones.
+if test -z "$CONFIG_SITE"; then
+  if test "x$prefix" != xNONE; then
+    CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site"
+  else
+    CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site"
+  fi
+fi
+for ac_site_file in $CONFIG_SITE; do
+  if test -r "$ac_site_file"; then
+    echo "loading site script $ac_site_file"
+    . "$ac_site_file"
+  fi
+done
+
+if test -r "$cache_file"; then
+  echo "loading cache $cache_file"
+  . $cache_file
+else
+  echo "creating cache $cache_file"
+  > $cache_file
+fi
+
+ac_ext=c
+# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options.
+ac_cpp='$CPP $CPPFLAGS'
+ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5'
+ac_link='${CC-cc} -o conftest $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5'
+cross_compiling=$ac_cv_prog_cc_cross
+
+if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then
+  # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu.
+  if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then
+    ac_n= ac_c='
+' ac_t='	'
+  else
+    ac_n=-n ac_c= ac_t=
+  fi
+else
+  ac_n= ac_c='\c' ac_t=
+fi
+
+
+ac_aux_dir=
+for ac_dir in $srcdir $srcdir/.. $srcdir/../..; do
+  if test -f $ac_dir/install-sh; then
+    ac_aux_dir=$ac_dir
+    ac_install_sh="$ac_aux_dir/install-sh -c"
+    break
+  elif test -f $ac_dir/install.sh; then
+    ac_aux_dir=$ac_dir
+    ac_install_sh="$ac_aux_dir/install.sh -c"
+    break
+  fi
+done
+if test -z "$ac_aux_dir"; then
+  { echo "configure: error: can not find install-sh or install.sh in $srcdir $srcdir/.. $srcdir/../.." 1>&2; exit 1; }
+fi
+ac_config_guess=$ac_aux_dir/config.guess
+ac_config_sub=$ac_aux_dir/config.sub
+ac_configure=$ac_aux_dir/configure # This should be Cygnus configure.
+
+# Find a good install program.  We prefer a C program (faster),
+# so one script is as good as another.  But avoid the broken or
+# incompatible versions:
+# SysV /etc/install, /usr/sbin/install
+# SunOS /usr/etc/install
+# IRIX /sbin/install
+# AIX /bin/install
+# AIX 4 /usr/bin/installbsd, which doesn't work without a -g flag
+# AFS /usr/afsws/bin/install, which mishandles nonexistent args
+# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff"
+# ./install, which can be erroneously created by make from ./install.sh.
+echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6
+echo "configure:554: checking for a BSD compatible install" >&5
+if test -z "$INSTALL"; then
+if eval "test \"`echo '$''{'ac_cv_path_install'+set}'`\" = set"; then
+  echo $ac_n "(cached) $ac_c" 1>&6
+else
+    IFS="${IFS= 	}"; ac_save_IFS="$IFS"; IFS="${IFS}:"
+  for ac_dir in $PATH; do
+    # Account for people who put trailing slashes in PATH elements.
+    case "$ac_dir/" in
+    /|./|.//|/etc/*|/usr/sbin/*|/usr/etc/*|/sbin/*|/usr/afsws/bin/*|/usr/ucb/*) ;;
+    *)
+      # OSF1 and SCO ODT 3.0 have their own names for install.
+      # Don't use installbsd from OSF since it installs stuff as root
+      # by default.
+      for ac_prog in ginstall scoinst install; do
+        if test -f $ac_dir/$ac_prog; then
+	  if test $ac_prog = install &&
+            grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then
+	    # AIX install.  It has an incompatible calling convention.
+	    :
+	  else
+	    ac_cv_path_install="$ac_dir/$ac_prog -c"
+	    break 2
+	  fi
+	fi
+      done
+      ;;
+    esac
+  done
+  IFS="$ac_save_IFS"
+
+fi
+  if test "${ac_cv_path_install+set}" = set; then
+    INSTALL="$ac_cv_path_install"
+  else
+    # As a last resort, use the slow shell script.  We don't cache a
+    # path for INSTALL within a source directory, because that will
+    # break other packages using the cache if that directory is
+    # removed, or if the path is relative.
+    INSTALL="$ac_install_sh"
+  fi
+fi
+echo "$ac_t""$INSTALL" 1>&6
+
+# Use test -z because SunOS4 sh mishandles braces in ${var-val}.
+# It thinks the first close brace ends the variable substitution.
+test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}'
+
+test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644'
+
+trap '' 1 2 15
+cat > confcache <<\EOF
+# This file is a shell script that caches the results of configure
+# tests run on this system so they can be shared between configure
+# scripts and configure runs.  It is not useful on other systems.
+# If it contains results you don't want to keep, you may remove or edit it.
+#
+# By default, configure uses ./config.cache as the cache file,
+# creating it if it does not exist already.  You can give configure
+# the --cache-file=FILE option to use a different cache file; that is
+# what configure does when it calls configure scripts in
+# subdirectories, so they share the cache.
+# Giving --cache-file=/dev/null disables caching, for debugging configure.
+# config.status only pays attention to the cache file if you give it the
+# --recheck option to rerun configure.
+#
+EOF
+# The following way of writing the cache mishandles newlines in values,
+# but we know of no workaround that is simple, portable, and efficient.
+# So, don't put newlines in cache variables' values.
+# Ultrix sh set writes to stderr and can't be redirected directly,
+# and sets the high bit in the cache file unless we assign to the vars.
+(set) 2>&1 |
+  case `(ac_space=' '; set) 2>&1 | grep ac_space` in
+  *ac_space=\ *)
+    # `set' does not quote correctly, so add quotes (double-quote substitution
+    # turns \\\\ into \\, and sed turns \\ into \).
+    sed -n \
+      -e "s/'/'\\\\''/g" \
+      -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p"
+    ;;
+  *)
+    # `set' quotes correctly as required by POSIX, so do not add quotes.
+    sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p'
+    ;;
+  esac >> confcache
+if cmp -s $cache_file confcache; then
+  :
+else
+  if test -w $cache_file; then
+    echo "updating cache $cache_file"
+    cat confcache > $cache_file
+  else
+    echo "not updating unwritable cache $cache_file"
+  fi
+fi
+rm -f confcache
+
+trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
+
+test "x$prefix" = xNONE && prefix=$ac_default_prefix
+# Let make expand exec_prefix.
+test "x$exec_prefix" = xNONE && exec_prefix='${prefix}'
+
+# Any assignment to VPATH causes Sun make to only execute
+# the first set of double-colon rules, so remove it if not needed.
+# If there is a colon in the path, we need to keep it.
+if test "x$srcdir" = x.; then
+  ac_vpsub='/^[ 	]*VPATH[ 	]*=[^:]*$/d'
+fi
+
+trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15
+
+# Transform confdefs.h into DEFS.
+# Protect against shell expansion while executing Makefile rules.
+# Protect against Makefile macro expansion.
+cat > conftest.defs <<\EOF
+s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g
+s%[ 	`~#$^&*(){}\\|;'"<>?]%\\&%g
+s%\[%\\&%g
+s%\]%\\&%g
+s%\$%$$%g
+EOF
+DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '`
+rm -f conftest.defs
+
+
+# Without the "./", some shells look in PATH for config.status.
+: ${CONFIG_STATUS=./config.status}
+
+echo creating $CONFIG_STATUS
+rm -f $CONFIG_STATUS
+cat > $CONFIG_STATUS <<EOF
+#! /bin/sh
+# Generated automatically by configure.
+# Run this file to recreate the current configuration.
+# This directory was configured as follows,
+# on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
+#
+# $0 $ac_configure_args
+#
+# Compiler output produced by configure, useful for debugging
+# configure, is in ./config.log if it exists.
+
+ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]"
+for ac_option
+do
+  case "\$ac_option" in
+  -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r)
+    echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion"
+    exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;;
+  -version | --version | --versio | --versi | --vers | --ver | --ve | --v)
+    echo "$CONFIG_STATUS generated by autoconf version 2.12.1"
+    exit 0 ;;
+  -help | --help | --hel | --he | --h)
+    echo "\$ac_cs_usage"; exit 0 ;;
+  *) echo "\$ac_cs_usage"; exit 1 ;;
+  esac
+done
+
+ac_given_srcdir=$srcdir
+ac_given_INSTALL="$INSTALL"
+
+trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15
+EOF
+cat >> $CONFIG_STATUS <<EOF
+
+# Protect against being on the right side of a sed subst in config.status.
+sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g;
+ s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF
+$ac_vpsub
+$extrasub
+s%@SHELL@%$SHELL%g
+s%@CFLAGS@%$CFLAGS%g
+s%@CPPFLAGS@%$CPPFLAGS%g
+s%@CXXFLAGS@%$CXXFLAGS%g
+s%@DEFS@%$DEFS%g
+s%@LDFLAGS@%$LDFLAGS%g
+s%@LIBS@%$LIBS%g
+s%@exec_prefix@%$exec_prefix%g
+s%@prefix@%$prefix%g
+s%@program_transform_name@%$program_transform_name%g
+s%@bindir@%$bindir%g
+s%@sbindir@%$sbindir%g
+s%@libexecdir@%$libexecdir%g
+s%@datadir@%$datadir%g
+s%@sysconfdir@%$sysconfdir%g
+s%@sharedstatedir@%$sharedstatedir%g
+s%@localstatedir@%$localstatedir%g
+s%@libdir@%$libdir%g
+s%@includedir@%$includedir%g
+s%@oldincludedir@%$oldincludedir%g
+s%@infodir@%$infodir%g
+s%@mandir@%$mandir%g
+s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g
+s%@INSTALL_DATA@%$INSTALL_DATA%g
+
+CEOF
+EOF
+
+cat >> $CONFIG_STATUS <<\EOF
+
+# Split the substitutions into bite-sized pieces for seds with
+# small command number limits, like on Digital OSF/1 and HP-UX.
+ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script.
+ac_file=1 # Number of current file.
+ac_beg=1 # First line for current file.
+ac_end=$ac_max_sed_cmds # Line after last line for current file.
+ac_more_lines=:
+ac_sed_cmds=""
+while $ac_more_lines; do
+  if test $ac_beg -gt 1; then
+    sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file
+  else
+    sed "${ac_end}q" conftest.subs > conftest.s$ac_file
+  fi
+  if test ! -s conftest.s$ac_file; then
+    ac_more_lines=false
+    rm -f conftest.s$ac_file
+  else
+    if test -z "$ac_sed_cmds"; then
+      ac_sed_cmds="sed -f conftest.s$ac_file"
+    else
+      ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file"
+    fi
+    ac_file=`expr $ac_file + 1`
+    ac_beg=$ac_end
+    ac_end=`expr $ac_end + $ac_max_sed_cmds`
+  fi
+done
+if test -z "$ac_sed_cmds"; then
+  ac_sed_cmds=cat
+fi
+EOF
+
+cat >> $CONFIG_STATUS <<EOF
+
+CONFIG_FILES=\${CONFIG_FILES-"Makefile"}
+EOF
+cat >> $CONFIG_STATUS <<\EOF
+for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then
+  # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in".
+  case "$ac_file" in
+  *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'`
+       ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;;
+  *) ac_file_in="${ac_file}.in" ;;
+  esac
+
+  # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories.
+
+  # Remove last slash and all that follows it.  Not all systems have dirname.
+  ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'`
+  if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then
+    # The file is in a subdirectory.
+    test ! -d "$ac_dir" && mkdir "$ac_dir"
+    ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`"
+    # A "../" for each directory in $ac_dir_suffix.
+    ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'`
+  else
+    ac_dir_suffix= ac_dots=
+  fi
+
+  case "$ac_given_srcdir" in
+  .)  srcdir=.
+      if test -z "$ac_dots"; then top_srcdir=.
+      else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;;
+  /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;;
+  *) # Relative path.
+    srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix"
+    top_srcdir="$ac_dots$ac_given_srcdir" ;;
+  esac
+
+  case "$ac_given_INSTALL" in
+  [/$]*) INSTALL="$ac_given_INSTALL" ;;
+  *) INSTALL="$ac_dots$ac_given_INSTALL" ;;
+  esac
+
+  echo creating "$ac_file"
+  rm -f "$ac_file"
+  configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure."
+  case "$ac_file" in
+  *Makefile*) ac_comsub="1i\\
+# $configure_input" ;;
+  *) ac_comsub= ;;
+  esac
+
+  ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"`
+  sed -e "$ac_comsub
+s%@configure_input@%$configure_input%g
+s%@srcdir@%$srcdir%g
+s%@top_srcdir@%$top_srcdir%g
+s%@INSTALL@%$INSTALL%g
+" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file
+fi; done
+rm -f conftest.s*
+
+EOF
+cat >> $CONFIG_STATUS <<EOF
+
+EOF
+cat >> $CONFIG_STATUS <<\EOF
+
+exit 0
+EOF
+chmod +x $CONFIG_STATUS
+rm -fr confdefs* $ac_clean_files
+test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1
+
diff --git a/doc/configure.in b/doc/configure.in
new file mode 100644
index 0000000..2575d44
--- /dev/null
+++ b/doc/configure.in
@@ -0,0 +1,5 @@
+dnl Process this file with autoconf to produce a configure script.
+AC_PREREQ(2.5)
+AC_INIT(dejagnu.texi)
+AC_PROG_INSTALL
+AC_OUTPUT(Makefile)
diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi
new file mode 100644
index 0000000..68c4008
--- /dev/null
+++ b/doc/dejagnu.texi
@@ -0,0 +1,3572 @@
+o\input texinfo               @c             -*- Texinfo -*-
+@finalout
+@setfilename dejagnu.info
+@c
+@c This file documents the GNU Testing Framework ``DejaGnu''
+@c
+@c Copyright (C) 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
+@c
+@c This text may be freely distributed under the terms of the GNU
+@c General Public License.
+@c
+
+@c FIXME---MAIN TODO LIST!
+@c
+@c * Revisit organization.
+@c 
+@c * discuss Tcl/expect basics---enough to get started (see seminar notes).
+@c   Maybe this would permit abbreviating appendices.
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* DejaGnu: (dejagnu).            The GNU testing framework.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@syncodeindex ky cp
+@syncodeindex fn cp
+
+@setchapternewpage odd
+@settitle DejaGnu Testing Framework
+@titlepage
+@title The DejaGnu Testing Framework
+@subtitle for DejaGnu Version 1.3
+@sp 1
+@subtitle Jan 1996
+@author Rob Savoye
+@page
+
+@tex
+{\parskip=0pt \hfill Cygnus Support}
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@noindent
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+
+@ifinfo
+Copyright @copyright{} 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries a copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+
+@node Top
+@top DejaGnu
+
+DejaGnu is a framework for running test suites on software tools.
+
+This file describes version 1.3 of DejaGnu.
+
+@menu
+* Overview::                    What is DejaGnu?
+* What is New::                 What is new in this release.
+* Invoking runtest::            Using `runtest', the main test driver
+* Customizing::			Setting `runtest' defaults
+* Internals::                   The DejaGnu implementation
+* Tests::                       How to write a test case
+* Extending::                   New tools, new targets, and new hosts
+* Installation::                Configuring and Installing DejaGnu
+* Index::                       Index
+@end menu
+@end ifinfo
+
+@iftex
+@raggedbottom
+@end iftex
+
+@node Overview
+@chapter What is DejaGnu?
+@cindex overview
+
+DejaGnu is a framework for testing other programs.  Its purpose is to
+provide a single front end for all tests.  Beyond this, DejaGnu offers
+several advantages for testing:
+
+@enumerate
+@item
+The flexibility and consistency of the DejaGnu framework make it easy
+to write tests for any program.
+
+@item
+DejaGnu provides a layer of abstraction which allows you to write tests
+that are portable to any host or target where a program must be tested.
+ For instance, a test for GDB can run (from any Unix based host) on any
+target architecture that DejaGnu supports. Currently DejaGnu runs tests
+on several single board computers, whose operating software ranges from
+just a boot monitor to a full-fledged, Unix-like realtime OS.
+
+@item
+All tests have the same output format.  This makes it easy to integrate
+testing into other software development processes. DejaGnu's output is
+designed to be parsed by other filtering script, and it is also human
+readable.
+@end enumerate
+
+DejaGnu is written in @code{expect}, which in turn uses @dfn{Tcl}---Tool
+command language.
+
+@cindex @code{expect} script names
+@kindex .exp
+@cindex suffix, @code{expect} scripts
+Running tests requires two things: the testing framework, and the test
+suites themselves.  Tests are usually written in @code{expect} using
+Tcl, but you can also use a Tcl script to run a test suite that is not
+based on @code{expect}.  (@code{expect} script filenames conventionally
+use @samp{.exp} as a suffix; for example, the main implementation of the
+DejaGnu test driver is in the file @file{runtest.exp}.)
+
+
+@menu
+* Running Tests::               A first look at running DejaGnu tests
+* Sample Test::                 What does a DejaGnu test case look like?
+* Design Goals::                Goals behind DejaGnu
+* Posix::			DejaGnu conforms to POSIX 1003.3
+* Future Directions::           Where is DejaGnu going?
+* Tcl and Expect::              Reading more about Tcl and Expect
+@end menu
+
+@node What is New
+@chapter What is new in this release ?
+@cindex What is New
+
+This release has a number of substantial changes over version 1.2. The
+most visible change is that the version of expect and Tcl included in
+the release are up-to-date with the current stable net releases. Other
+changes are:
+
+@enumerate
+@item
+@c FIXME: add a link to the config section
+The config sub-system in DejaGnu has been completely redesigned. It now
+supports testing on remote hosts as well as remote targets.
+
+@item
+More builtin support for building target binaries with the correct
+linker flags. Currently this only works with GCC, preferably with a
+target support by @code{libgloss}.
+
+@item
+Lots of little bug fixes from a year of heavy use here at Cygnus
+Support.
+
+@item
+DejaGnu now uses @code{autoconf} for configuration.
+
+@item
+New test cases for DejaGnu have been added for the new features, plus
+the "--tool" option bug in the 1.2 testsuite has been fixed.
+
+@item
+The @code{--tool} option is now optional.
+
+@item
+@code{runtest} when searching for test drivers ignores all directories
+named SCCS, RCS, and CVS.
+
+@item
+There is now a generic keyword based test harness that uses comments in
+source code to control how each test case gets built and run.
+
+@item
+There is now some support for running a testsuite with multiple passes
+and multiple targets.
+
+@end enumerate
+
+@node Running Tests
+@section Running existing tests
+@cindex existing tests, running
+@cindex running tests
+@cindex tests, running
+
+@kindex make check
+To run tests from an existing collection, first use @code{configure} as
+usual to set up the source directory containing the tests.  Then try
+running
+
+@example
+make check
+@end example
+
+@cindex @code{check} makefile target
+If the @code{check} target exists, it usually saves you some
+trouble---for instance, it can set up any auxiliary programs or other
+files needed by the tests.
+
+@cindex auxiliary files, building
+Once you have run @samp{make check} to build any auxiliary files, you
+might want to call the test driver @code{runtest} directly to repeat the
+tests.  You may also have to call @code{runtest} directly for test
+collections with no @code{check} target in the @file{Makefile}.
+
+@c force page break to avoid losing footnote to another page
+@page
+@cindex @code{runtest}, most common options
+@cindex options for @code{runtest}, common
+Typically, you must use two command-line options: @samp{--tool}, to
+specify which set of tests to run@footnote{@samp{--tool} selects a
+particular suite of tests, @emph{not} the name of the executable program
+to run.  @xref{Config Values,,Configuration dependent values}, for
+information on the variables that you can use to specify the names of
+programs to run.}, and @samp{--srcdir}, to specify where to find test
+directories.
+
+For example, if the directory @file{gdb/testsuite} contains a collection
+of DejaGnu tests for @sc{gdb}, you can run them like this:
+
+@example
+eg$ cd gdb/testsuite
+eg$ runtest --tool gdb
+@exdent @emph{Test output follows, ending with:}
+
+		=== gdb Summary ===
+
+# of expected passes 508
+# of expected failures 103
+/usr/latest/bin/gdb version 4.14.4 -nx
+@end example
+
+You can use the option @samp{--srcdir} to point to some other directory
+containing a collection of tests:
+
+@smallexample
+eg$ runtest --tool gdb --srcdir /devo/gdb/testsuite
+@end smallexample
+
+@cindex native configuration
+@cindex cross configuration
+These examples assume a @dfn{native} configuration, where the same
+computer runs both @code{runtest} and the tests themselves.  When you
+have a @dfn{cross} configuration, the tests run on a different computer,
+controlled by the host running @code{runtest}.  In this situation, you
+need the option @samp{--name} to specify the network address for the
+other computer:
+
+@smallexample
+eg$ runtest --tool gdb --name vx9.munist.com
+@end smallexample
+
+If you always use the same option values, you can record them in a file
+called @file{site.exp}, rather than typing them each time.  @xref{Config
+Values,,Setting defaults for @code{runtest} options}.
+
+By default, @code{runtest} prints only the names of the tests it runs,
+output from any tests that have unexpected results, and a summary
+showing how many tests passed and how many failed.  To display output
+from all tests (whether or not they behave as expected), use the
+@samp{--all} option.  For more verbose output about processes being run,
+communication, and so on, use @samp{--verbose}. To see even more output,
+use multiple @samp{--verbose} options.  @xref{Invoking runtest,,Using
+@code{runtest}}, for a more detailed explanation of each @code{runtest}
+option.
+
+Test output goes into two files in your current directory: summary
+output in @file{@var{tool}.sum}, and detailed output in
+@file{@var{tool}.log}.  (@var{tool} refers to the collection of tests;
+for example, after a run with @samp{--tool gdb}, look for output files
+@file{gdb.sum} and @file{gdb.log}.)  @xref{Output Files,,The files
+DejaGnu writes}.
+
+@node Sample Test
+@section What does a DejaGnu test look like?
+
+@cindex example
+Each DejaGnu test is an @code{expect} script; the tests vary widely in
+complexity, depending on the nature of the tool and the feature tested.
+
+@kindex gdb.t00/echo.exp
+@kindex echo.exp
+Here is a very simple @sc{gdb} test---one of the simplest tests shipped
+with DejaGnu (extracted from @file{gdb.t00/echo.exp}):@footnote{More
+recent @sc{gdb} tests use the @samp{gdb_test} procedure.
+An equivalent test using that procedure is @samp{ gdb_test "echo Hello
+world!" "Hello world!" }}
+@c FIXME! include xref in footnote, when gdb_test documented in some manual.
+@c @xref{}.
+@c Extra spaces in @samp above avoid running end ' against " inside.
+
+@cartouche
+@smallexample
+# send a string to the GDB stdin:
+send "echo Hello world!\n"
+
+# inspect the GDB stdout for the correct reply,
+# and determine whether the test passes or fails:
+expect @{
+  -re "Hello world.*$prompt $"    @{ pass "Echo test" @}
+  -re "$prompt $"                 @{ fail "Echo test" @}
+  timeout                         @{ fail "(timeout) Echo test" @}
+  @}
+@end smallexample
+@end cartouche
+
+Though brief, this example is a complete test.  It illustrates some of
+the main features of DejaGnu test scripts:
+
+@itemize @bullet
+@item
+The test case does not start the tested program (@sc{gdb} in this case);
+all test scripts for interactive tools can assume the corresponding tool
+is running.
+
+@item
+Comments start with @samp{#}.
+
+@item
+The main commands you use to control a tested program are @code{send}
+(to give it commands) and @code{expect} (to analyze its responses).
+
+@item
+The @code{expect} command uses a list of pairs; a pattern (regular
+expression if @samp{-re} specified), followed by an action to run if the
+pattern matches output from the program.  Only the action for the
+@emph{first} matching pattern will execute.
+
+@item
+Test cases use the commands @code{pass} and @code{fail} to record the
+test outcome.
+@end itemize
+
+@node Design Goals
+@section Design goals
+@cindex design goals
+
+DejaGnu grew out of the internal needs of Cygnus Support.  Cygnus
+maintains and enhances a variety of free programs in many different
+environments, and we needed a testing tool that:
+
+@itemize @bullet
+@item
+is useful to developers while fixing bugs;
+
+@item
+automates running many tests during a software release process;
+
+@item
+is portable among a variety of host computers;
+
+@item
+supports cross-development testing;
+
+@item
+permits testing interactive programs, like @sc{gdb}; and
+
+@item
+permits testing batch oriented programs, like @sc{gcc}.
+@end itemize
+
+Some of the requirements proved challenging.  For example, interactive
+programs do not lend themselves very well to automated testing.  But all
+the requirements are important: for instance, it is imperative to make
+sure that @sc{gdb} works as well when cross-debugging as it does in a
+native configuration.
+
+Probably the greatest challenge was testing in a cross-development
+environment (which can be a real nightmare).  Most cross-development
+environments are customized by each developer.  Even when buying
+packaged boards from vendors there are many differences.  The
+communication interfaces vary from a serial line to ethernet.  DejaGnu
+was designed with a modular communication setup, so that each kind of
+communication can be added as required, and supported thereafter.  Once
+a communication procedure is coded, any test can use it.  Currently
+DejaGnu can use @code{rsh}, @code{rlogin}, @code{telnet}, @code{tip},
+@code{kermit}, and @code{mondfe} for remote communications.
+
+@cindex name ``DejaGnu''
+@cindex DejaGnu, the name
+@cindex Menapace, Julia
+Julia Menapace first coined the term ``Deja Gnu'' to describe an earlier
+testing framework at Cygnus Support.  When we replaced it with the
+Expect-based framework, it was like DejaGnu all over again@dots{}
+
+@node Posix
+@section A POSIX conforming test framework
+
+@cindex POSIX conformance
+@cindex standard conformance: POSIX 1003.3
+DejaGnu conforms to the @sc{posix} standard for test frameworks.
+
+@cindex TET
+@sc{posix} standard 1003.3 defines what a testing framework needs to
+provide, in order to permit the creation of @sc{posix} conformance
+test suites. This standard is primarily oriented to running @sc{posix}
+conformance tests, but its requirements also support testing of features
+not related to @sc{posix} conformance.  @sc{posix} 1003.3 does not
+specify a particular testing framework, but at this time there is only
+one other @sc{posix} conforming test framework:
+@sc{tet}.@footnote{@sc{tet} was created by Unisoft for a consortium
+comprised of X/Open, Unix International, and the Open Software
+Foundation.}
+
+The @sc{posix} documentation refers to @dfn{assertions}.  An assertion
+is a description of behavior.  For example, if a standard says ``The sun
+shall shine'', a corresponding assertion might be ``The sun is
+shining.''  A test based on this assertion would pass or fail depending
+on whether it is daytime or nighttime.  It is important to note that the
+standard being tested is never 1003.3; the standard being tested is some
+other standard, for which the assertions were written.
+
+As there is no test suite to test @emph{testing frameworks} for
+@sc{posix} 1003.3 conformance, verifying conformance to this standard is
+done by repeatedly reading the standard and experimenting.  One of the
+main things 1003.3 does specify is the set of allowed output messages,
+and their definitions.  Four messages are supported for a required
+feature of @sc{posix} conforming systems, and a fifth for a conditional
+feature. DejaGnu supports the use of all five output messages; in this
+sense a test suite that uses exactly these messages can be considered
+@sc{posix} conforming.  These definitions specify the output of a test
+case:
+
+@ftable @code
+@cindex success, POSIX definition
+@item PASS
+A test has succeeded.  That is, it demonstrated that the assertion is true.
+
+@cindex XFAIL, avoiding for POSIX
+@item XFAIL
+@sc{posix} 1003.3 does not incorporate the notion of expected failures,
+so @code{PASS}, instead of @code{XPASS}, must also be returned for test
+cases which were expected to fail and did not.  This means that
+@code{PASS} is in some sense more ambiguous than if @code{XPASS} is also
+used.  For information on @code{XPASS} and @code{XFAIL}, see
+@ref{Invoking runtest,,Using @code{runtest}}.
+
+@item FAIL
+@cindex failure, POSIX definition
+A test @emph{has} produced the bug it was intended to capture.  That is,
+it has demonstrated that the assertion is false.  The @code{FAIL}
+message is based on the test case only.  Other messages are used to
+indicate a failure of the framework.
+
+As with @code{PASS}, @sc{posix} tests must return @code{FAIL} rather
+than @code{XFAIL} even if a failure was expected.
+
+@item UNRESOLVED
+@cindex ambiguity, required for POSIX
+A test produced indeterminate results.  Usually, this means the test
+executed in an unexpected fashion; this outcome requires that a human
+being go over results, to determine if the test should have passed or
+failed.  This message is also used for any test that requires human
+intervention because it is beyond the abilities of the testing
+framework.  Any unresolved test should resolved to @code{PASS} or
+@code{FAIL} before a test run can be considered finished.
+
+Note that for @sc{posix}, each assertion must produce a test result
+code.  If the test isn't actually run, it must produce @code{UNRESOLVED}
+rather than just leaving that test out of the output.  This means that
+you have to be careful when writing tests, to not carelessly use tcl
+statements like @code{return}---if you alter the flow of control of the
+tcl code you must insure that every test still produces some result code.
+
+Here are some of the ways a test may wind up @code{UNRESOLVED}:
+
+@itemize @bullet
+@item
+A test's execution is interrupted.
+
+@item
+A test does not produce a clear result. This is usually because there
+was an @code{ERROR} from DejaGnu while processing the test, or because there
+were three or more @code{WARNING} messages. Any @code{WARNING} or
+@code{ERROR} messages can invalidate the output of the test.  This
+usually requires a human being to examine the output to
+determine what really happened---and to improve the test case.
+
+@item
+A test depends on a previous test, which fails.
+
+@item
+The test was set up incorrectly.
+@end itemize
+
+@item UNTESTED
+A test was not run.  This is a placeholder, used when there is no
+real test case yet.
+@end ftable
+
+@noindent
+The only remaining output message left is intended to test features that
+are specified by the applicable @sc{posix} standard as conditional:
+
+@ftable @code
+@item UNSUPPORTED
+There is no support for the tested case.  This may mean that a
+conditional feature of an operating system, or of a compiler, is not
+implemented.  DejaGnu also uses this message when a testing environment
+(often a ``bare board'' target) lacks basic support for compiling or
+running the test case.  For example, a test for the system subroutine
+@code{gethostname} would never work on a target board running only a
+boot monitor.
+@end ftable
+  
+DejaGnu uses the same output procedures to produce these messages for
+all test suites, and these procedures are already known to conform to
+@sc{posix} 1003.3.  For a DejaGnu test suite to conform to @sc{posix}
+1003.3, you must avoid the @code{setup_xfail} procedure as described in
+the @code{PASS} section above, and you must be careful to return
+@code{UNRESOLVED} where appropriate, as described in the
+@code{UNRESOLVED} section above.
+
+@node Future Directions
+@section Future directions
+@cindex future directions
+
+In the near future, there are two parallel directions for DejaGnu
+development.  The first is to add support for more hosts and targets.
+
+The second would permit testing programs with a more complex interface,
+whether text based or GUI based.  Two components already exist: a Tcl
+based X window toolkit, and a terminal package for @code{expect}. Both
+of these could be merged into DejaGnu in a way that permits testing
+programs that run in each environment.
+
+Meanwhile, we hope DejaGnu enables the creation of test suites for
+conformance to @sc{ansi} C and C++, to @sc{posix}, and to other
+standards.  We encourage you to make any test suites you create freely
+available, under the same terms as DejaGnu itself.
+
+@node Tcl and Expect
+@section Tcl and Expect
+@cindex tool command language
+@cindex tcl
+@cindex Ousterhout, John K.
+Tcl was introduced in a paper by John K. Ousterhout at the 1990 Winter
+Usenix conference, @cite{Tcl: An Embeddable Command Language}.  That
+paper is included in PostScript form in the @file{doc} subdirectory of
+the Tcl distribution. The version of Tcl included in DejaGnu at this time is
+Tcl 7.4p3. 
+
+@cindex @code{expect} scripting language
+@cindex Libes, Don
+Don Libes introduced @code{expect} in his paper @cite{expect: Curing
+Those Uncontrollable Fits of Interaction} at the 1990 Summer Usenix
+conference.  The paper is included in PostScript form in the
+@code{expect} distribution (as are several other papers about
+@code{expect}). The version of expect included in DejaGnu at this time
+is expect 5.18.0.
+
+@node Invoking runtest
+@chapter Using @code{runtest}
+@cindex invoking
+@cindex running
+@cindex command line options
+@cindex options
+
+@cindex @code{runtest} description
+@cindex DejaGnu test driver
+@code{runtest} is the executable test driver for DejaGnu.  You can
+specify two kinds of things on the @code{runtest} command line: command
+line options, and Tcl variables for the test scripts.  The options are
+listed alphabetically below.  
+
+@cindex exit code from @code{runtest}
+@cindex @code{runtest} exit code
+@code{runtest} returns an exit code of @code{1} if any test
+has an unexpected result; otherwise (if all tests pass or fail as
+expected) it returns @code{0} as the exit code.
+
+@code{runtest} flags the outcome of each test as one of these cases.
+(@xref{Posix,,A POSIX conforming test framework}, for a discussion of
+how @sc{posix} specifies the meanings of these cases.)
+
+@table @code
+@item PASS
+@kindex PASS
+@cindex successful test
+@cindex test, successful
+The most desirable outcome: the test succeeded, and was expected to
+succeed.
+
+@item XPASS
+@kindex XPASS
+@cindex successful test, unexpected
+@cindex unexpected success
+A pleasant kind of failure: a test was expected to fail, but succeeded.
+This may indicate progress; inspect the test case to determine whether
+you should amend it to stop expecting failure.
+
+@item FAIL
+@kindex FAIL
+@cindex failing test, unexpected
+@cindex test, failing
+A test failed, although it was expected to succeed.  This may indicate
+regress; inspect the test case and the failing software to locate the bug.
+
+@item XFAIL
+@kindex XFAIL
+@cindex expected failure
+@cindex failing test, expected
+A test failed, but it was expected to fail.  This result indicates no
+change in a known bug.  If a test fails because the operating system
+where the test runs lacks some facility required by the test, the
+outcome is @code{UNSUPPORTED} instead.
+
+@item UNRESOLVED
+@kindex UNRESOLVED
+@cindex test, unresolved outcome
+Output from a test requires manual inspection; the test suite could not
+automatically determine the outcome.  For example, your tests can report
+this outcome is when a test does not complete as expected.
+
+@item UNTESTED
+@kindex UNTESTED
+@cindex untested properties
+A test case is not yet complete, and in particular cannot yet produce a
+@code{PASS} or @code{FAIL}.  You can also use this outcome in dummy
+``tests'' that note explicitly the absence of a real test case
+for a particular property.
+
+@item UNSUPPORTED
+@kindex UNSUPPORTED
+@cindex unsupported test
+@cindex test, unsupported
+A test depends on a conditionally available feature that does not exist
+(in the configured testing environment).  For example, you can use this
+outcome to report on a test case that does not work on a particular
+target because its operating system support does not include a required
+subroutine.
+@end table
+
+@code{runtest} may also display the following messages:
+
+@table @code
+@item ERROR
+@kindex ERROR
+@cindex problem, detected by test case
+@cindex test case cannot run
+Indicates a major problem (detected by the test case itself) in running
+the test. This is usually an unrecoverable error, such as a missing file
+or loss of communication to the target.  (@sc{posix} test suites should
+not emit this message; use @code{UNSUPPORTED}, @code{UNTESTED}, or
+@code{UNRESOLVED} instead, as appropriate.)
+
+@item WARNING
+@kindex WARNING
+@cindex test case warnings
+Indicates a possible problem in running the test. Usually warnings
+correspond to recoverable errors, or display an important message about
+the following tests.
+
+@item NOTE
+@kindex NOTE
+@cindex test case messages
+An informational message about the test case.
+@end table
+
+This is the full set of command line options that @code{runtest}
+recognizes.  Arguments may be abbreviated to the shortest unique string.
+
+@cindex @code{runtest} option list
+@cindex option list, @code{runtest}
+@smallexample
+runtest --tool @var{tool}  [ @var{testsuite}.exp @dots{} ]
+[ @var{testsuite}.exp="testfile1 @dots{}" ]
+[ @var{tclvar}=@var{value}@dots{} ]
+[ --all ]  [ --baud @var{baud-rate} ]  [ --connect @var{type} ]
+[ --debug ]  [ --help ]  [ --host @var{string} ]
+[ --mail "@var{name} @dots{}" ]  [ --name @var{string} ]
+[ --name @var{name} ]  [ --outdir @var{path} ]
+[ --objdir @var{path} ]  [ --reboot ]
+[ --srcdir @var{path} ]  [ --strace @var{n} ]
+[ --target @var{string} --build @var{string} ]
+[ -v | --verbose ]  [ -V | --version ]  [ --D@var{n} ]
+@end smallexample
+
+@table @code
+@item --tool @var{tool}
+@cindex selecting tests for a tool
+@cindex @code{--tool} (@code{runtest} option)
+@var{tool} specifies what set of tests to run, and what initialization
+module to use.  @var{tool} is used @emph{only} for these two purposes:
+it is @emph{not} used to name the executable program to test.
+Executable tool names (and paths) are recorded in @file{site.exp}
+(@pxref{Config Values,,Configuration dependent values}), and you can
+override them by specifying Tcl variables on the command line.
+
+For example, including @samp{--tool gcc} on the @code{runtest} command
+line runs tests from all test subdirectories whose names match
+@file{gcc.*}, and uses one of the initialization modules named
+@file{config/*-gcc.exp}.  To specify the name of the compiler (perhaps
+as an alternative path to what @code{runtest} would use by default), use
+@samp{GCC=@var{binname}} on the @code{runtest} command line.
+
+@item @var{testsuite}.exp @dots{}
+@cindex selecting a range of tests
+@cindex tests, running specifically
+@cindex naming tests to run
+Specify the names of testsuites to run.
+By default, @code{runtest} runs all tests for the tool, but you can
+restrict it to particular testsuites by giving the names of the @samp{.exp}
+@code{expect} scripts that control them.
+
+@var{testsuite}.exp may not include path information; use plain filenames.
+
+@item @var{testfile}.exp="testfile1 @dots{}"
+@cindex selecting a range of tests
+@cindex tests, running specifically
+@cindex naming tests to run
+Specify a subset of tests in a suite to run.
+For compiler or assembler tests, which often use a single @samp{.exp}
+script covering many different source files, this option allows you to
+further restrict the tests by listing particular source files to compile.
+Some tools even support wildcards here.  The wildcards supported depend
+upon the tool, but typically they are @code{?}, @code{*}, and @code{[chars]}.
+
+@item @var{tclvar}=@var{value}
+@kindex @var{tclvar}=@var{value}
+@cindex Tcl variables, defining for @code{runtest}
+@cindex command line Tcl variable definition
+@cindex @code{runtest}, variable defns on cmdline
+You can define Tcl variables for use by your test scripts in the same
+style used with @code{make} for environment variables.  For example,
+@samp{runtest GDB=gdb.old} defines a variable called @samp{GDB}; when
+your scripts refer to @samp{$GDB} in this run, they use the value
+@samp{gdb.old}.
+
+The default Tcl variables used for most tools are defined in the main
+DejaGnu @code{Makefile}; their values are captured in the
+@file{site.exp} file.  @xref{Config Values,,Configuration dependent
+values}.
+
+@item --all
+@cindex @code{--all} (@code{runtest} option)
+@cindex test output, displaying all
+Display all test output.  By default, @code{runtest} shows only the
+output of tests that produce unexpected results; that is, tests with
+status @samp{FAIL} (unexpected failure), @samp{XPASS} (unexpected
+success), or @samp{ERROR} (a severe error in the test case itself).
+Specify @samp{--all} to see output for tests with status @samp{PASS}
+(success, as expected) @samp{XFAIL} (failure, as expected), or
+@samp{WARNING} (minor error in the test case itself).
+
+@item --baud @var{baud-rate}
+@itemx -b @var{baud-rate}
+@cindex baud rate, specifying
+@cindex bps, specifying
+@cindex @code{--baud} (@code{runtest} option)
+@cindex @code{-b} (@code{runtest} option)
+Set the default baud rate to something other than 9600.  (Some serial
+interface programs, like @code{tip}, use a separate initialization file
+instead of this value.)
+
+@item --connect @var{type}
+@cindex connecting to target
+@cindex @code{--connect} (@code{runtest} option)
+@cindex remote testbed, connecting to
+@cindex @code{rlogin}, remote testing via
+@cindex @code{telnet}, remote testing via
+@cindex @code{rsh}, remote testing via
+@cindex @code{tip}, remote testing via
+@cindex @code{kermit}, remote testing via
+@cindex @code{mondfe}, remote testing via
+@cindex remote testing via @code{rlogin}
+@cindex remote testing via @code{telnet}
+@cindex remote testing via @code{rsh}
+@cindex remote testing via @code{tip}
+@cindex remote testing via @code{kermit}
+@cindex remote testing via @code{mondfe}
+Connect to a target testing environment as specified by @var{type}, if
+the target is not the computer running @code{runtest}.  For example, use
+@samp{--connect} to change the program used to connect to a ``bare
+board'' boot monitor.  The choices for @var{type} in the DejaGnu 1.0
+distribution are @samp{rlogin}, @samp{telnet}, @samp{rsh}, @samp{tip},
+@samp{kermit}, and @samp{mondfe}.
+
+@noindent
+The default for this option depends on the configuration (@pxref{Cross
+Targets,,Remote targets supported}).  The default is chosen to be the
+most convenient communication method available, but often other
+alternatives work as well; you may find it useful to try alternative
+connect methods if you suspect a communication problem with your testing
+target.
+
+@item --debug
+@cindex @code{--debug} (@code{runtest} option)
+@cindex debug log for test cases
+@cindex test cases, debug log
+@cindex @code{dbg.log} file
+Turns on the @code{expect} internal debugging output.  Debugging output
+is displayed as part of the @code{runtest} output, and logged to a file
+called @file{dbg.log}.  The extra debugging output does @emph{not}
+appear on standard output, unless the verbose level is greater than 2
+(for instance, to see debug output immediately, specify @samp{--debug -v
+-v}).  The debugging output shows all attempts at matching the test
+output of the tool with the scripted patterns describing expected
+output.  The output generated with @samp{--strace} also goes into
+@file{dbg.log}.
+
+@item --help
+@itemx -he
+@cindex @code{--help} (@code{runtest} option)
+@cindex help with @code{runtest}
+@cindex @code{runtest}, listing options
+Prints out a short summary of the @code{runtest} options, then exits
+(even if you also specify other options).
+
+@item --host @var{string}
+@cindex @code{--host} (@code{runtest} option)
+@cindex specifying the host config name
+@cindex host config name, changing
+@var{string} is a full configuration ``triple'' name as used by
+@code{configure}.  Use this option to override the default string
+recorded by your configuration's choice of host.  This choice does not
+change how anything is actually configured unless --build is also
+specified; it affects @emph{only} DejaGnu procedures that compare the
+host string with particular values.  The procedures @code{ishost},
+@code{istarget}, @code{isnative}, and @code{setup_xfail} are affected by
+@samp{--host}. In this usage, @code{host} refers to the machine that the
+tests are to be run on, which may not be the same as the @code{build}
+machine. If @code{--build} is also specified, then @code{--host} refers
+to the machine that the tests wil, be run on, not the machine DejaGnu is
+run on.
+
+@item --build @var{string}
+@cindex @code{--build} (@code{runtest} option)
+@cindex specifying the build config name
+@cindex build config name, changing
+@var{string} is a full configuration ``triple'' name as used by
+@code{configure}. This is the type of machine DejaGnu and the tools to
+be tested are built on. For a normal cross this is the same as the host,
+but for a canadian cross, they are seperate.
+
+@item --name @var{name}
+@cindex specifying target name
+@cindex target machine name
+@cindex @code{--name} (@code{runtest} option)
+@var{name} is a name for the particular testing target machine (for
+cross testing).  If the testing target has IP network support (for
+example, @code{RPC} or @code{NFS}), this is the network name for the
+target itself.  (@var{name} is @emph{not the configuration string} you
+specify as a target with @code{configure}; the @samp{--name} option
+names a particular target, rather than describing a class of targets.)
+For targets that connect in other ways, the meaning of the @var{name}
+string depends on the connection method.  @xref{Cross Targets,,Remote
+targets supported}.
+
+@item --name @var{string}
+@cindex remote test machine name
+@cindex name for remote test machine
+Specify a network name of testing target or its host.  The particular
+names that are meaningful with @samp{--name} will depend on your site
+configuration, and on the connection protocol: for example, @code{tip}
+connections require names from a serial line configuration file (usually
+called @file{/etc/remote}), while @code{telnet} connections use IP
+hostnames.
+
+@item --objdir @var{path}
+@cindex @code{--objdir} (@code{runtest} option)
+@cindex object directory
+@cindex test programs, auxiliary
+@cindex auxiliary test programs
+Use @var{path} as the top directory containing any auxiliary compiled
+test code. This defaults to @file{.}.  Use this option to locate
+pre-compiled test code.  You can normally prepare any auxiliary files
+needed with @code{make}.
+
+@item --outdir @var{path}
+@cindex output directory
+@cindex @code{--outdir} (@code{runtest} option)
+@cindex log files, where to write
+Write output logs in directory @var{path}.  The default is @samp{.}, the
+directory where you start @code{runtest}.  This option affects only the
+summary and the detailed log files @file{@var{tool}.sum} and
+@file{@var{tool}.log}.  The DejaGnu debug log @file{dbg.log} always
+appears (when requested) in the local directory.
+
+@item --reboot
+@cindex rebooting remote targets
+@cindex @code{--reboot} (@code{runtest} option)
+Reboot the target board when @code{runtest} initializes.
+Usually, when running tests on a separate target board, it is safer to
+reboot the target to be certain of its state.  However, when developing
+test scripts, rebooting takes a lot of time.
+
+@item --srcdir @var{path}
+@cindex source directory
+@cindex @code{--srcdir} (@code{runtest} option)
+Use @var{path} as the top directory for test scripts to run.
+@code{runtest} looks in this directory for any subdirectory whose name
+begins with the toolname (specified with @samp{--tool}).  For instance,
+with @samp{--tool gdb}, @code{runtest} uses tests in subdirectories
+@file{gdb.*} (with the usual shell-like filename expansion).  If you do
+not use @samp{--srcdir}, @code{runtest} looks for test directories under
+the current working directory.
+
+@item --strace @var{n}
+@cindex @code{--strace} (@code{runtest} option)
+@cindex tracing Tcl commands
+@cindex @code{expect} internal tracing
+Turn on internal tracing for @code{expect}, to @var{n} levels deep. By
+adjusting the level, you can control the extent to which your output
+expands multi-level Tcl statements.  This allows you to ignore some
+levels of @code{case} or @code{if} statements.  Each procedure call or
+control structure counts as one ``level''.
+
+The output is recorded in the same file, @file{dbg.log}, used for output
+from @samp{--debug}.
+
+@item --target @var{string}
+@cindex @code{--target} (@code{runtest} option)
+@cindex specifying the target configuration
+@cindex target configuration, specifying
+Use this option to override the default setting (running native tests).
+@var{string} is a full configuration ``triple''
+name@footnote{Configuration triples have the form
+@samp{@var{cpu}-@var{vendor}-@var{os}}.} as used by @code{configure}.
+This option changes the configuration @code{runtest} uses for the
+default tool names, and other setup information.  @xref{Using
+configure,,Using @code{configure}, configure.info, Cygnus configure},
+for details about @code{configure} names.
+
+@item --verbose
+@itemx -v
+@cindex @code{--verbose} (@code{runtest} option)
+@cindex @code{-v} (@code{runtest} option)
+@cindex turning on output
+@cindex output, additional
+Turns on more output.  Repeating this option increases the amount of
+output displayed.  Level one (@samp{-v}) is simply test output. Level
+two (@samp{-v -v}) shows messages on options, configuration, and process
+control.  Verbose messages appear in the detailed (@file{*.log}) log
+file, but not in the summary (@file{*.sum}) log file.
+
+@item --version
+@itemx -V
+@cindex @code{-V} (@code{runtest} option)
+@cindex @code{--version} (@code{runtest} option)
+@cindex version numbers
+Prints out the version numbers of DejaGnu, @code{expect} and Tcl, and
+exits without running any tests.
+
+@item -D0
+@itemx -D1
+@cindex starting the tcl debugger
+@cindex tcl debugger
+@c FIXME!!! we should say a *lot* more about this debugger
+Start the internal Tcl debugger.  The Tcl debugger supports breakpoints,
+single stepping, and other common debugging activities.  (See @cite{A
+Debugger for Tcl Applications} by Don Libes. @footnote{Distributed in
+PostScript form with @code{expect} as the file@*
+@file{expect/tcl-debug.ps}.})
+
+If you specify @samp{-D1}, the @code{expect} shell stops at a breakpoint
+as soon as DejaGnu invokes it.
+
+If you specify @samp{-D0}, DejaGnu starts as usual, but you can enter
+the debugger by sending an interrupt (e.g. by typing @key{C-c}).
+@end table
+
+@node Customizing
+@chapter Setting @code{runtest} defaults
+
+@kindex site.exp
+@cindex variables of DejaGnu, defaults
+The site configuration file, @file{site.exp}, captures
+configuration-dependent values and propagates them to the DejaGnu test
+environment using Tcl variables.  This ties the DejaGnu test scripts
+into the @code{configure} and @code{make} programs.
+
+@cindex @file{site.exp}, multiple
+@cindex overriding @file{site.exp}
+DejaGnu supports more than one @file{site.exp} file.  The multiple
+instances of @file{site.exp} are loaded in a fixed order built into
+DejaGnu (the more local last). The first file loaded is the optional
+@code{~/.dejagnurc}, then the local files, and finally the global file.
+
+@enumerate
+@item
+There is am optional ``master'' @file{site.exp}, capturing configuration values
+that apply to DejaGnu across the board, in each configuration-specific
+subdirectory of the DejaGnu library directory.  @code{runtest} loads
+these values first. @xref{Installation,,Configuring and Installing
+DejaGnu}.  The master @file{site.exp} contains the default values for
+all targets and hosts supported by DejaGnu. This master file is
+identified by setting the environment variable @code{DEJAGNU} to the
+name of the file. This is also refered to as the ``global'' config file.
+
+@item
+Any directory containing a configured test suite also has a
+@file{site.exp}, capturing configuration values specific to the tool
+under test.  Since @code{runtest} loads these values last, the
+individual test configuration can either rely on and use, or override,
+any of the global values from the ``master'' @file{site.exp}.
+
+You can usually generate or update the testsuite @file{site.exp} by
+typing @samp{make site.exp} in the test suite directory, after the test
+suite is configured.
+
+@item
+You can also have a file in your home directory called
+@code{.dejagnurc}. This gets loaded first before the other config
+files. Usually this is used for personal stuff, like setting
+@code{all_flag} so all the output gets printed, or verbosity levels.
+@end enumerate
+
+You can further override the default values in a user-editable section
+of any @file{site.exp}, or by setting variables on the @code{runtest}
+command line.
+
+@menu
+* Config Values::               Variables used in the configuration file.
+* Master Config File::          The master configuration file.
+* Local Config File::           The local configuration file.
+* Personal Config File::        The personal configuration file.
+@end menu
+
+@node Config Values, Master Config File, , Customizing
+@subsection Config Variables
+@cindex configuration dependent defaults
+@cindex setting defaults for DejaGnu variables
+
+@c NOTE: default values are given via @code{"fubar"} rather than the
+@c    more conventional @samp{fubar} to permit a consistent and clear
+@c    notation for the empty string (@code{""}), which will work exactly as
+@c    typed.
+
+DejaGnu uses a named array in Tcl to hold all the info for each
+machine. In the case of a canadian cross, this means host information as
+well as target information. The named array is called
+@code{target_info}, and it has two indices. The following fields are
+part of the array. 
+
+@table @code
+@item name
+The name of the target. (mostly for error messages) This
+should also be the string used for this target's array.
+It should also be the same as the linker script so we
+can find them dynamically. This should be the same as the argument used
+for @code{push_target@{@}}.
+
+@item ldflags 
+This is the linker flags required to produce a fully linked
+executable. For @code{libgloss} supported targets this is usually just
+the name of the linker script. 
+
+@item config
+The target canonical for this target. This is used by some init files to
+make sure the target is supported.
+
+@item cflags
+The flags required to produce an object file from a source file.
+
+@item connect
+This is the connectmode for this target. This is for both IP and
+serial connections. Typically this is either @code{telnet},
+@code{rlogin}, or @code{rsh}.
+
+@item target
+This is the hostname of the target. This is for TCP/IP based connections,
+and is also used for version of tip that use /etc/remote. 
+
+@item serial
+This is the serial port. This is typically /dev/tty? or com?:.
+
+@item netport
+This is the IP port. This is commonly used for telneting to target
+boards that are connected to a terminal server. In that case the IP port
+specifies the which serial port to use.
+
+@item baud 
+This is the baud rate for a serial port connection.
+
+@item x10
+This is the parameters for an x10 controller. These are simple devices
+that let us power cycle or reset a target board remotely. 
+
+@item fileid
+This is the fileid or spawn id of of the connection.
+
+@item prompt
+a glob style pattern to recognize the prompt.
+
+@item abbrev
+abbreviation for tool init files.
+
+@item ioport
+This is the port for I/O on dual port systems. In this configuration,
+the main serial port @code{0} is usually used for stdin and stdout,
+which the second serial port can be used for debugging.
+@end table
+
+The first index into the array is the same value as used in the
+@code{name} field. This is usually a short version of the name of the
+target board. For an example, here's the settings I use for  my
+@code{Motorola's} @code{IDP} board and my @code{Motorola} 6U VME
+@code{MVME135-1} board. (both m68k targets)
+       
+@cartouche
+@smallexample
+# IDP board
+set target_info(idp,name)       "idp"
+set target_info(idp,ldflags)    "-Tidp.ld"
+set target_info(idp,config)     m68k-unknown-aout
+set target_info(idp,cflags)     ""
+set target_info(idp,connect)    telnet
+set target_info(idp,target)     "s7"
+set target_info(idp,serial)     "tstty7"
+set target_info(idp,netport)    "wharfrat:1007"
+set target_info(idp,baud)       "9600"
+# MVME 135 board
+set target_info(idp,name)       "mvme"
+set target_info(idp,ldflags)    "-Tmvme.ld"
+set target_info(idp,config)     m68k-unknown-aout
+set target_info(idp,cflags)     ""
+set target_info(idp,connect)    telnet
+set target_info(idp,target)     "s8"
+set target_info(idp,serial)     "tstty8"
+set target_info(idp,netport)    "wharfrat:1008"
+set target_info(idp,baud)       "9600"
+@end smallexample
+@end cartouche
+
+DejaGnu can use this information to switch between multiple targets in
+one test run. This is done through the use of the @code{push_target}
+procedure, which is discussed elsewhere.
+@c FIXME: write that section and put an xref here
+
+This array can also hold information for a remote host, which is used
+when testing a candain cross. In this case, the only thing different is
+the index is just @code{host}. Here's the settings I use to run tests
+on my NT machine while running DejaGnu on a Unix machine. (in this case
+a Linux box)
+
+@cartouche
+@smallexample
+set target_info(host,name)      "nt-host"
+set target_info(host,config)    "386-unknown-winnt"
+set target_info(host,connect)   "telnet"
+set target_info(host,target)    "ripple"
+@end smallexample
+@end cartouche
+
+There is more info on how to use these variables in the sections on the
+config files. @xref{Master Config File,,Configuration Files}.
+
+@cindex option defaults
+@cindex @code{runtest} option defaults
+@cindex variables for option defaults
+@cindex defaults, option
+In the user editable second section of @file{site.exp}, you can not only
+override the configuration variables captured in the first section, but
+also specify default values for all the @code{runtest} command line
+options.  Save for @samp{--debug}, @samp{--help}, and @samp{--version},
+each command line option has an associated Tcl variable.  Use the Tcl
+@code{set} command to specify a new default value (as for the
+configuration variables).  The following table describes the
+correspondence between command line options and variables you can set in
+@file{site.exp}.  @xref{Invoking runtest,,Running the Tests}, for
+explanations of the command-line options.
+
+@kindex all_flag
+@kindex baud
+@kindex reboot
+@kindex outdir
+@kindex objdir
+@kindex runtests
+@kindex ignoretests
+@kindex srcdir
+@kindex tracelevel
+@kindex targetname
+@kindex connectmode
+@kindex tool
+@kindex target_triplet
+@kindex host_triplet
+@kindex build_triplet
+@kindex verbose
+
+@cindex command line option variables
+@cindex Tcl variables for option defaults
+@cindex default options, controlling
+@cindex options, Tcl variables for defaults
+
+@ifinfo
+@display
+runtest      Tcl   
+option     variable     description
+__________ ________     ___________________________________________
+
+--all      all_flag     display all test results if set
+
+--baud     baud         set the default baud rate to something other
+                        than 9600.
+--connect  connectmode  @samp{rlogin}, @samp{telnet}, @samp{rsh}, 
+                        @samp{kermit}, @samp{tip}, or @samp{mondfe}
+
+--outdir   outdir       directory for @file{@var{tool}.sum} and @file{@var{tool}.log}
+
+--objdir   objdir       directory for pre-compiled binaries
+
+--reboot   reboot       reboot the target if set to @code{"1"};
+                        do not reboot if set to @code{"0"} (the default)
+
+--srcdir   srcdir       directory of test subdirectories
+
+--strace   tracelevel   a number: Tcl trace depth
+
+--tool     tool         name of tool to test; identifies init, test subdir
+
+--verbose  verbose      verbosity level.  As option, use multiple times;
+                        as variable, set a number, 0 or greater
+--target   target_triplet The canonical configuration string for the target.
+--host     host_triplet The canonical configuration string for the host.
+--build    build_triplet The canonical configuration string for the
+                        build host.
+
+@end display
+@end ifinfo
+
+@tex
+\vbox{\halign{\hfil \tt #\quad &\quad\tt #\hfil &\hbox{\vtop{{\raggedright\parindent=0pt\parskip=5pt\hsize=2.75in\rm#\strut\par}}}\hfill\cr
+\cr
+{\it runtest}&{\it Tcl}\cr
+{\it option}&{\it variable}&{\it description}\cr
+\noalign{\hrule width\hsize}\cr
+--all     &all\_flag    &display all test results if set\cr
+--baud    &baud         &set the default baud rate to something other
+                        than 9600.\cr
+--connect &connectmode &@samp{rlogin}, @samp{telnet}, @samp{rsh},
+                        @samp{kermit}, @samp{tip}, or @samp{mondfe}\cr
+--mail    &mailing\_list&address list for mailing test output\cr
+--name    &targetname  &network name of testing target or its host\cr
+--outdir  &outdir      &directory for @file{@var{tool}.sum} and @file{@var{tool}.log}\cr
+--objdir  &objdir      &directory for compiled binaries\cr
+--reboot  &reboot      &reboot the target if set to @code{"1"};
+do not reboot if set to @code{"0"} (the default)\cr
+--srcdir  &srcdir      &directory of test subdirectories\cr
+--strace  &tracelevel  &a number: Tcl trace depth\cr
+--tool    &tool        &name of tool to test; identifies init, test subdir\cr
+--verbose &verbose     &verbosity level.  As option, use multiple times;
+                        as variable, set a number, 0 or greater\cr
+--target  &target\_triplet
+        &The canonical configuration string for the target.\cr
+--host   &host\_triplet &The canonical configuration string for the host.\cr
+--build  &build\_triplet &The canonical configuration string for the
+                        build host.\cr
+}}
+@end tex
+
+@node Master Config File, Local Config File, Config Values, Customizing
+@subsection Master Config File
+@cindex master @file{site.exp}
+@cindex @file{site.exp} for all of DejaGnu
+The master config file is where all the target specific config variables
+get set for a whole site get set. The idea is that for a centralized
+testing lab where people have to share a target between multiple
+developers. There are settings for both remote targets and remote hosts. 
+Here's an example of a Master Config File (also called the Global config
+file) for a @emph{canadian cross}. A canadian cross is when you build
+and test a cross compiler on a machine other than the one it's to be
+hosted on.
+
+Here we have the config settings for our California office. Note that
+all config values are site dependant. Here we have two sets of values
+that we use for testing m68k-aout cross compilers. As both of these
+target boards has a different debugging protocol, we test on both of
+them in sequence.
+
+@cartouche
+@smallexample
+global CFLAGS
+global CXXFLAGS
+
+case "$target_triplet" in @{
+    @{ "native" @} @{
+        set target_abbrev unix
+    @}
+    @{ "m68*-unknown-aout" @} @{
+        set target_abbrev               "rom68k"
+        # IDP target                    # IDP board with rom68k monitor
+        set target_info(idp,name)       "idp"
+        set target_info(idp,ldflags)    "-Tidp.ld"
+        set target_info(idp,config)     m68k-unknown-aout
+        set target_info(idp,cflags)     ""
+        set target_info(idp,connect)    telnet
+        set target_info(idp,target)     "s7"
+        set target_info(idp,serial)     "tstty12"
+        set target_info(idp,netport)    "truckin:1007"
+        set target_info(idp,baud)       "9600"
+        # MVME target                   # Motorola MVME 135 with BUG monitor
+        set target_info(mvme,name)      "mvme"
+        set target_info(mvme,ldflags)   "-Tmvme.ld"
+        set target_info(mvme,config)    m68k-unknown-aout
+        set target_info(mvme,cflags)    ""
+        set target_info(mvme,connect)   telnet
+        set target_info(mvme,target)    "s4"
+        set target_info(mvme,serial)    "tstty8"
+        set target_info(mvme,netport)   "truckin:1004"
+        set target_info(mvme,baud)      "9600"
+     @}
+@}
+@end smallexample
+@end cartouche
+
+ In this case, we have support for several remote hosts for
+our m68k-aout cross compiler. Typically the remote Unix hosts run
+DejaGnu locally, but we also use them for debugging the testsuites when
+we find problems in running on remote hosts. Expect won't run on NT, so
+DejaGnu is run on the local build machine, and it'll connect to the NT
+host and run all the tests for this cross compiler on that host.
+
+@smallexample
+@cartouche
+case "$host_triplet" in @{
+    "native" @{
+    @}
+    "i?86-*-linux*" @{                   # Linux host
+        set target_info(host,name)      "linux-host"
+        set target_info(host,config)    $host_triplet
+        set target_info(host,connect)   rlogin
+        set target_info(host,target)    chinadoll
+    @}
+    "i?86-*-winnt                       # NT host
+        set target_info(host,name)      "nt-host"
+        set target_info(host,config)    i386-unknown-winnt
+        set target_info(host,connect)   telnet
+        set target_info(host,target)    ripple
+    @}
+    "hppa*-hp-hpux*" @{                  # HP-UX host
+        set target_info(host,name)      "hpux-host"
+        set target_info(host,config)    $host_triplet
+        set target_info(host,connect)   rlogin
+        set target_info(host,target)    slipknot
+        @}
+    "sparc-sun-sunos*" @{                # SunOS (sun4)
+        set target_info(host,name)      "sunos-host"
+        set target_info(host,config)    $host_triplet
+        set target_info(host,connect)   rlogin
+        set target_info(host,target)    darkstar
+    @}
+@}
+@end cartouche
+@end smallexample
+
+@node Local Config File, Personal Config File, Master Config File, Customizing
+@subsection Local Config File
+@cindex local @file{site.exp}
+@cindex @file{site.exp} for each tool
+It is usually more convenient to keep these ``manual overrides'' in the
+@file{site.exp} local to each test directory, rather than in the
+``master'' @file{site.exp} in the DejaGnu library.
+
+All local @file{site.exp} usually files have two sections, separated by
+comment text. The first section is the part that is generated by
+@code{make}. It is essentially a collection of Tcl variable definitions
+based on @file{Makefile} environment variables. Since they are generated
+by @code{make}, they contain the values as specified by
+@code{configure}.  (You can also customize these values by using the
+@samp{--site} option to @code{configure}.)  In particular, this section
+contains the @file{Makefile} variables for host and target configuration
+data. Do not edit this first section; if you do, your changes are replaced
+next time you run @code{make}.
+
+The first section starts with:
+
+@cartouche
+@smallexample
+## these variables are automatically generated by make ##
+# Do not edit here. If you wish to override these values
+# add them to the last section
+@end smallexample
+@end cartouche
+
+In the second section, you can override any default values (locally to
+DejaGnu) for all the variables.  The 
+second section can also contain your preferred defaults for all the
+command line options to @code{runtest}. This allows you to easily
+customize @code{runtest} for your preferences in each configured
+test-suite tree, so that you need not type options repeatedly on the
+command line.  (The second section may also be empty, if you do not wish
+to override any defaults.)
+
+The first section ends with this line:
+
+@cartouche
+@smallexample
+## All variables above are generated by configure. Do Not Edit ##
+@end smallexample
+@end cartouche
+
+You can make any changes under this line. If you wish to redefine a
+variable in the top section, then just put a duplicate value in this
+second section. Usually the values defined in this config file are
+related to the configuration of the test run. This is the ideal place to
+set the variables @code{host_triplet}, @code{build_triplet},
+@code{target_triplet}. All other variables are tool dependant. ie for
+testing a compiler, the value for @var{CC} might be set to a freshly
+built binary, as opposed to one in the user's path.
+
+@node Personal Config File, , Local Config File, Customizing
+@subsection Personal Config File
+@cindex personal config @file{site.exp}
+@cindex @file{site.exp} for each person
+The personal config file is used to customize @code{runtest's} behaviour
+for each person. It's typically used to set the user prefered setting
+for verbosity, and any experimental Tcl procedures. My personal
+@file{~/.dejagnurc} file looks like:
+
+@cartouche
+@smallexample
+set all_flag 1
+set RLOGIN /usr/ucb/rlogin
+set RSH /usr/ucb/rsh
+@end smallexample
+@end cartouche
+
+Here I set @code{all_flag} so I see all the test cases that PASS along
+with the ones that FAIL. I also set @var{RLOGIN} and @code{RSH} to the
+BSD version. I have @code{kerberos} installed, and when I rlogin to a
+target board, it usually isn't supported. So I use the non secure
+versions of these programs rather than the default that's in my path. 
+
+@node Internals
+@chapter The DejaGnu Implementation
+@cindex operating principles
+@cindex internal details
+
+DejaGnu is entirely written in @code{expect}, which uses Tcl as a
+command language.  @code{expect} serves as a very programmable shell;
+you can run any program, as with the usual Unix command shells---but
+once the program is started, your @code{expect} script has fully
+programmable control of its input and output.  This does not just apply
+to the programs under test; @code{expect} can also run any auxiliary
+program, such as @code{diff} or @code{sh}, with full control over its
+input and output.
+
+DejaGnu itself is merely a framework for the set of test suites
+distributed separately for each @sc{gnu} tool.  Future releases of
+@sc{gnu} tools will include even more tests, developed throughout the
+free software community.
+
+@kindex runtest.exp
+@code{runtest} is the glue to tie together and manage the test scripts.
+The @code{runtest} program is actually a simple Bourne shell script that
+locates a copy of the @code{expect} shell and then starts the main Tcl
+code, @code{runtest.exp}. @code{runtest.exp} itself has these essential
+functions:
+
+@enumerate
+@item
+Parse the command line options, load the library files, and load the
+default configuration files.
+
+@item
+Locating the individual test scripts.  @code{runtest.exp} locates the tests
+by exploiting a straightforward naming convention based on the string
+you specify with the @samp{--tool} option.
+
+@item
+Providing an extended test environment, by defining additional Tcl
+procedures beyond those already in @code{expect}.
+
+@item
+Locating target-dependent functions, to standardize the test environment
+across a wide variety of test platforms.
+@end enumerate
+
+@menu
+* Names::                       Conventions for using tool names
+* Init Module::			Initialization module
+* DejaGnu Builtins::            DejaGnu provides these Tcl procedures
+* Target Dependent::            Procedures supplied by the init module
+* Cross Targets::		Remote targets supported
+* Input Files::                 The files DejaGnu depends on
+* Output Files::                The files DejaGnu produces
+@end menu
+
+@node Names
+@section Conventions for using tool names
+
+@cindex @code{--tool} and naming conventions
+@cindex tool names and naming conventions
+@cindex naming conventions
+DejaGnu uses @samp{$tool}, the name of the tool under test, to tie
+together the testing configuration in a straightforward but flexible
+way. If there is only one testsuite for a particular application, then
+@samp{$tool} is optional.
+
+@samp{$tool} is @emph{not} used to invoke the tool, since sites that run
+multiple configurations of a particular tool often call each
+configuration by a different name.  @code{runtest} uses the
+configuration-dependent variables captured in @file{site.exp} to
+determine how to call each tool.
+
+@cindex directory names and @code{--tool}
+@cindex test directories, naming
+@code{runtest} uses tool names to find directories containing tests.
+@code{runtest} scans the source directory (specified with
+@code{--srcdir}) for all directories whose names start with the tool
+name. It is a common practice to put a period after the tool part of the
+name. For instance, directories that start with
+@samp{g++.} contain @sc{g++} tests.  To add a new test, just put it in
+any directory (create an entirely new directory, if you wish) whose name
+follows this convention.
+
+@cindex @code{exp} filename suffix
+@cindex test filename
+@cindex filename for test files
+A test is any file in an appropriately named subdirectory whose name
+ends in @samp{.exp} (the conventional way of naming @code{expect}
+scripts).  These simple naming conventions make it as simple as possible
+to install new tests: all you must do is put the test in the right
+directory.
+
+@cindex order of tests
+@cindex tests, running order
+@code{runtest} sorts the tests in each subdirectory by name (using the
+Tcl @code{lsort} command) and runs them in the resulting order.
+
+@node Init Module
+@section Initialization module
+@cindex tool initialization
+@cindex setting up targets
+
+@c FIXME! should this node be merged with "Target dependent"?
+
+@cindex init file, purpose
+@cindex starting interactive tools
+@cindex initialization
+The initialization module (or ``init file'') has two purposes: to
+provide tool and target dependent procedures, and to start up an
+interactive tool to the point where it is ready to operate.  The latter
+includes establishing communications with the target.  All the tests for
+interactive programs assume that the tool is already running and
+communicating.  Initialization modules for non-interactive programs may
+only need to supply the support functions.
+
+@cindex init file name
+@cindex name, initialization module
+Each test suite directory must contain (in its @file{config}
+subdirectory) a separate initialization module for each target.  The
+appropriate init file is can be named several ways. The prefered name is
+the @emph{os} part of the canonical configuration name with @code{.exp}
+as the suffix. An example would be that for an @code{m68k-coff} system,
+the @code{target_os} part would be @code{coff}. The next way is for
+system where there are short filenames, or a shortcut is desired to
+refer to the OS name for that target. This is uses the value of
+@code{$target_abbrev} rather than the @code{target_os}.
+
+The final file looked for is simply @file{default.exp}. If there is only
+one operating system to support, then this file can be used. It's main
+purpose is to offer some support for new operating systems, or for
+unsupported cross targets. The last file looked for is
+@file{unknown.exp}. This is usually limited to error handling for
+unsupported targets. It's whole contents is typically.
+
+@cartouche
+@smallexample
+perror "Sorry, there is no support for this target"
+exit 1
+@end smallexample
+@end cartouche
+
+At the beginning of the init file, you must first determine the proper
+executable name of the tool to execute, since the actual name of the
+tool to be tested my vary from system to system. Here's an example
+for the @sc{GNU} C compiler.
+
+@cartouche
+@smallexample
+global AR
+# look for the archiver ar
+if ![info exists AR] @{
+    set AR [findfile $base_dir/../../binutils/ar $base_dir/../../binutils/ar [tr
+ansform ar]]
+    verbose "AR defaulting to $AR" 2
+@}
+@}
+
+global CFLAGS
+if ![info exists CFLAGS] then @{
+    set CFLAGS ""
+@}
+@end smallexample
+@end cartouche
+ 
+It is always a good idea to first check the variable, and only set it if
+it has not yet been defined.  Often the proper value of @code{AR} is set
+on the command line that invokes @file{runtest}.
+
+@kindex findfile
+The @code{findfile} procedure takes as it's first argument a file name
+to look for. The second argument is returned if the file is found, and
+the third argument is returned if the file is not found. @code{base_dir}
+is set internally by DejaGnu to the top level directory of the object
+tree.
+
+@kindex transform
+The @code{transform} procedure takes as its argument the native name of
+a tool (such as @samp{gcc} for the compiler), and returns the name as
+configured for that tool in the current installation.  (For example, a
+cross-compiling version of @sc{gnu} CC that generates MIPS code may be
+installed with a name like @code{mips-idt-ecoff-gcc}.)
+
+In a test running native, writing the Tcl code for initialization is
+usually quite simple.  For cross configurations, however, more elaborate
+instructions are usually needed to describe how to talk to a remote
+target.
+
+Each initialization module defines up to four procedures with standard
+names and purposes.  The names of these procedures begin with
+@samp{$tool}, the string that identifies tests for a particular tool:
+@code{$tool_start}, @code{$tool_load}, @code{$tool_exit}, and
+@code{$tool_version}.  For example, the start procedure for @sc{gdb} is
+called @code{gdb_start}.  (Since start procedures are used differently
+for batch and interactive tools, however, @code{runtest} itself never
+calls the start procedure.  Init files for interactive tools are
+expected to end by running the start procedure.)
+
+@cindex utilities, loading from init file
+@cindex defaults, setting in init file
+The initialization module is also a good place to call @code{load_lib}
+to get any collections of utility procedures meant for a family of test
+cases, and to set up default values for any additional Tcl variables
+needed for a specific set of tests.
+
+@xref{Target Dependent,,Target dependent procedures}, for full
+descriptions of these procedures.
+
+@node DejaGnu Builtins
+@section DejaGnu procedures
+@cindex built in procedures, DejaGnu
+
+DejaGnu provides these Tcl procedures for use in test scripts.
+You can also use any standard @code{expect} or Tcl function. These
+procedures are stored in libraries, which DejaGnu loads at
+runtime. Here's explanation of the library procedures that get loaded at
+runtime. All other librarys are optional, and need to be loaded by the
+testsuite.
+
+@menu
+* framework.exp::               Core Internal Procedures.
+* remote.exp::                  Procedures for remote communication.
+* utils.exp::                   Utility procedures.
+* target.exp::                  Cross target procedures.
+* debugger.exp::                Procedures for debugging your Tcl code.
+@end menu
+
+@node framework.exp, remote.exp, ,DejaGnu Builtins
+@subsection Core Internal Procedures
+@cindex Core Internal Procedures
+
+@xref{Posix,,A POSIX conforming test framework}, for more detailed
+explanations of the test outcomes (@samp{FAIL}, @samp{PASS},
+@samp{UNTESTED}, @samp{UNRESOLVED}, @samp{UNSUPPORTED}).
+
+@ftable @code
+@item perror "@var{string} @var{number}"
+@cindex test case, ERROR in
+@kindex ERROR
+Declares a severe error in the testing framework itself.
+@code{perror} writes in the log files a message beginning with
+@samp{ERROR}, appending the argument @var{string}. If the optional
+@var{number} is supplied, then this is used to set the internal count of
+errors to that value.
+
+As a side effect, @code{perror} also changes the effect of the next
+@code{pass} or @code{fail} command: the test outcome becomes
+@samp{UNRESOLVED}, since an automatic @samp{PASS} or @samp{FAIL} cannot
+be trusted after a severe error in the test framework.  If the optional
+numeric value is @samp{0}, then there are no further side effects to
+calling this function, and the following test outcome doesn't become
+@samp{UNRESOLVED}. This can be used for errors with no known side
+effects.
+
+@item warning "@var{string} @var{number}"
+@cindex test case, WARNING in
+@kindex WARNING
+Declares detection of a minor error in the test case itself.
+@code{warning} writes in the log files a message beginning with
+@samp{WARNING}, appending the argument @var{string}.  Use @code{warning}
+rather than @code{error} for cases (such as communication failure
+to be followed by a retry) where the test case can recover from the
+error.  If the optional @var{number} is supplied, then this is used to
+set the internal count of warnings to that value.
+
+As a side effect, @code{warning_threshold} or more calls to
+@code{warning} in a single test case also changes the effect of the next
+@code{pass} or @code{fail} command: the test outcome becomes
+@samp{UNRESOLVED} since an automatic @samp{PASS} or @samp{FAIL} may not
+be trustworthy after many warnings.  If the optional numeric value is
+@samp{0}, then there are no further side effects to calling this
+function, and the following test outcome doesn't become
+@samp{UNRESOLVED}. This can be used for errors with no known side
+effects.
+
+@item note "@var{string}"
+@cindex test case, informational messages
+@kindex NOTE
+Appends an informational message to the log file.
+@code{note} writes in the log files a message beginning with
+@samp{NOTE}, appending the argument @var{string}.  Use @code{note}
+sparingly.  @code{verbose} should be used for most such messages,
+but in cases where a message is needed in the log file regardless of
+the verbosity level use @code{note}.
+
+@item pass "@var{string}"
+@cindex test case, declaring success
+Declares a test to have passed.  @code{pass} writes in the 
+log files a message beginning with @samp{PASS} (or @code{XPASS}, if
+failure was expected), appending the argument @var{string}.
+
+@item fail "@var{string}"
+@cindex test case, declaring failure
+Declares a test to have failed.  @code{fail} writes in the 
+log files a message beginning with @samp{FAIL} (or @code{XFAIL}, if
+failure was expected), appending the argument @var{string}.
+
+@item unresolved "@var{string}"
+@cindex test case, declaring ambiguity
+Declares a test to have an unresolved outcome.  @code{unresolved} writes
+in the log file a message beginning with @samp{UNRESOLVED}, appending
+the argument @var{string}.  This usually means the test did not execute
+as expected, and a human being must go over results to determine if it
+passed or failed (and to improve the test case).
+
+@item untested "@var{string}"
+@cindex test case, declaring no test
+Declares a test was not run.  @code{untested} writes in the log file a
+message beginning with @samp{UNTESTED}, appending the argument
+@var{string}.  For example, you might use this in a dummy test whose
+only role is to record that a test does not yet exist for some feature.
+
+@item unsupported "@var{string}"
+@cindex test case, declaring no support
+Declares that a test case depends on some facility that does not exist
+in the testing environment.  @code{unsupported} writes in the log file a
+message beginning with @samp{UNSUPPORTED}, appending the argument
+@var{string}.
+
+@item get_warning_threshold
+@cindex test case, WARNING threshold
+Returns the current value of @code{warning_threshold}.
+The default value is 3.
+
+@item set_warning_threshold @var{threshold}
+@cindex test case, WARNING threshold
+Sets the value of @code{warning_threshold}.
+A value of @code{0} disables it: calls to @code{warning} will not turn
+a @samp{PASS} or @samp{FAIL} into an @samp{UNRESOLVED}.
+
+@item transform "@var{toolname}"
+@cindex transform tool name
+@cindex installed tool name
+@cindex tool name, as installed
+@cindex name transformations
+Generates a string for the name of a tool as it was configured and
+installed, given its native name (as the argument @var{toolname}).
+This makes the assumption that all tools are installed using the same
+naming conventions: it extrapolates from the invocation name for
+@file{runtest}.  For example, if you call @code{runtest} as
+@file{m68k-vxworks-runtest}, the result of @w{@samp{ transform "gcc" }}
+is @samp{m68k-vxworks-gcc}.
+
+@item ishost "@var{host}"
+@cindex host configuration test
+Tests for a particular @emph{host} environment.  If the currently
+configured host matches the argument string, the result is @code{1};
+otherwise the result is @code{0}.  @var{host} must be a full three-part
+@code{configure} host name; in particular, you may not use the shorter
+nicknames supported by @code{configure} (but you can use wildcard
+characters, using shell syntax, to specify sets of names). 
+
+@item istarget "@var{target}"
+@cindex target configuration test
+Tests for a particular @emph{target} environment.  If the currently
+configured target matches the argument string, the result is @code{1};
+otherwise the result is @code{0}.  @var{target} must be a full
+three-part @code{configure} target name; in particular, you may not use
+the shorter nicknames supported by @code{configure} (but you can use
+wildcard characters, using shell syntax, to specify sets of names). If it is
+passed a @code{NULL} string, then it returns the name of the build
+canonical configuration.
+
+@item isbuild "@var{host}"
+@cindex build host configuration test
+Tests for a particular @emph{build host} environment.  If the currently
+configured host matches the argument string, the result is @code{1};
+otherwise the result is @code{0}.  @var{host} must be a full three-part
+@code{configure} host name; in particular, you may not use the shorter
+nicknames supported by @code{configure} (but you can use wildcard
+characters, using shell syntax, to specify sets of names). If it is
+passed a @code{NULL} string, then it returns the name of the build
+canonical configuration.
+
+item is3way "@var{host}"
+@cindex canadian cross configuration test
+Tests for a canadian cross. This is when the tests will be run on a
+remotly hosted cross compiler. If it is a canadian cross, then the
+result is @code{1}; otherwise the result is @code{0}.
+
+@item isnative
+@cindex native configuration test
+Tests whether the current configuration has the same host and target.
+When it runs in a @emph{native} configuration this procedure returns a
+@code{1}; otherwise it returns a @code{0}.
+
+@item load_lib "@var{library-file}"
+@cindex load library file
+Loads the file @var{library-file} by searching a fixed path built into
+@code{runtest}.  If DejaGnu has been installed, it looks in a path
+starting with the installed library directory.  If you are running
+DejaGnu directly from a source directory, without first running
+@samp{make install}, this path defaults to the current directory.  In
+either case, it then looks in the current directory for a directory
+called @code{lib}.  If there are duplicate definitions, the last one
+loaded takes precedence over the earlier ones.
+ 
+@item setup_xfail "@var{config}  @r{[}@var{bugid}@r{]}"
+@c two spaces above to make it absolutely clear there's whitespace---a
+@c crude sort of italic correction!
+@cindex test case, expecting failure
+@cindex failure, expected
+@cindex expected failure
+Declares that the test is expected to fail on a particular set of
+configurations.  The @var{config} argument must be a list of full
+three-part @code{configure} target name; in particular, you may not use
+the shorter nicknames supported by @code{configure} (but you can use the
+common shell wildcard characters to specify sets of names).  The
+@var{bugid} argument is optional, and used only in the logging file
+output; use it as a link to a bug-tracking system such as @sc{gnats}
+(@pxref{Overview,, Overview, gnats.info, Tracking Bugs With GNATS}).
+
+@cindex @code{XFAIL}, producing
+@cindex @code{XPASS}, producing
+Once you use @code{setup_xfail}, the @code{fail} and @code{pass}
+procedures produce the messages @samp{XFAIL} and @samp{XPASS}
+respectively, allowing you to distinguish expected failures (and
+unexpected success!) from other test outcomes.
+
+@emph{Warning:} you must clear the expected failure after using
+@code{setup_xfail} in a test case.  Any call to @code{pass} or
+@code{fail} clears the expected failure implicitly; if the test has some
+other outcome, e.g. an error, you can call @code{clear_xfail} to clear
+the expected failure explicitly.  Otherwise, the expected-failure
+declaration applies to whatever test runs next, leading to surprising
+results.
+
+@item check_conditional_xfail @var{message} @var{targets} @var{includes} @var{excludes}
+@cindex test case, expecting a conditional failure
+@cindex failure, conditional expected
+@cindex conditional expected failure
+
+This procedure adds a condition xfail, based on compiler options used to
+create a test case executable. If an include options is found in the
+compiler flags, and it's the right architecture, it'll trigger an
+XFAIL. Otherwise it'll produce an ordinary FAIL. You can also specify
+flags to exclude. This makes a result be a FAIL, even if the included
+options are found. To set the conditional, set the variable
+@var{compiler_conditional_xfail_data} to the fields "[message string] [targets
+list] [includes list] [excludes list]" (descriptions below). This is the
+checked at pass/fail decision time, so there is no need to call the
+procedure yourself, unless you wish to know if it gets triggered. After
+a pass/fail, the variable is reset, so it doesn't effect other tests.
+
+The parameters are:
+
+@table @code
+@item message
+is the message to print with the normal test result
+
+@item targets
+is a string with the targets to activate this conditional on.
+
+@item includes
+is a list of sets of options to search for in the compiler options to
+activate this conditional. If any set of the options matches, then this
+conditional is true.
+
+@item excludes
+is a list of sets of options to search for in the compiler options to
+activate this conditional. If any set of the options matches,
+(regardless of whether any of the include sets match) then this
+conditional is de-activated.
+@end table
+
+returns:
+
+@table @code
+@item 1
+if the conditional is true
+@item 0
+if the conditional is false
+@end table
+
+An example of setting the variable would be:
+
+@cartouche
+@smallexample
+set compiler_conditional_xfail_data @{@ \
+        "I sure wish I knew why this was hosed" \
+        "sparc*-sun*-* *-pc-*-*" \
+        @{@"-Wall -v" "-O3"@}@ \
+        @{@"-O1" "-Map" @}@ \
+        @}@         
+@end smallexample
+@end cartouche
+
+  What this does is it matches only for these two targets if "-Wall -v" or 
+"-O3" is set, but neither "-O1" or "-Map" is set.
+
+  For a set to match, the options specified are searched for independantly of
+each other, so a "-Wall -v" matches either "-Wall -v" or "-v -Wall". A space
+seperates the options in the string. Glob-style regular expressions are also
+permitted.
+
+@item clear_xfail @var{config}
+@cindex cancelling expected failure
+@cindex expected failure, cancelling
+Cancel an expected failure (previously declared with @code{setup_xfail})
+for a particular set of configurations.  The @var{config} argument is a
+list of configuration target names.  It is only necessary to call
+@code{clear_xfail} if a test case ends without calling either
+@code{pass} or @code{fail}, after calling @code{setup_xfail}.
+
+@item verbose @r{[}-log@r{]} @r{[}-n@r{]} @r{[}--@r{]} "@var{string}" @var{number}
+@cindex @code{verbose} builtin function
+Test cases can use this function to issue helpful messages depending on
+the number of @samp{--verbose} options on the @code{runtest} command
+line.  It prints @var{string} if the value of the variable
+@code{verbose} is higher than or equal to the optional @var{number}. The
+default value for @var{number} is 1.  Use the optional @samp{-log} argument
+to cause @var{string} to always be added to the log file, even if it won't
+be printed.  Use the optional @samp{-n} argument to print @var{string}
+without a trailing newline.  Use the optional @samp{--} argument if
+@var{string} begins with "-".
+
+@end ftable
+
+@noindent
+@node remote.exp, utils.exp, framework.exp, DejaGnu Builtins
+@subsection Remote Communication Procedures
+
+@kindex remote.exp
+@kindex lib/remote.exp
+@cindex remote connection procedures
+@cindex communications procedures
+@file{lib/remote.exp} defines these functions, for establishing and
+managing communications:
+
+@emph{Procedures to establish a connection:} Each of these procedures
+tries to establish the connection up to three times before returning.
+Warnings (if retries will continue) or errors (if the attempt is
+abandoned) report on communication failures.  The result for any of
+these procedures is either @code{-1}, when the connection cannot be
+established, or the spawn ID returned by the @code{expect} command
+@code{spawn}.
+
+It use the value of the @code{connect} field in the @code{target_info}
+array (was @code{connectmode} as the type of connection to make. Current
+supported connection types are tip, kermit, telnet, rsh, rlogin, and
+netdata. If the @code{--reboot} option was used on the runtest command
+line, then the target is rebooted before the connection is made.
+
+@ftable @code
+
+@item remote_open @var{type}
+@cindex Opening a remote connection
+@emph{Remote Connection Procedure.} This is passed @emph{host} or
+@emph{target}. Host or target refers to whether it is a connection to a
+remote target, or a remote host. This opens the connection to the
+desired target or host using the default values in the configuration
+system. It returns that @code{spawn_id} of the process that manages the
+connection. This value can be used in @code{expect} or @code{exp_send}
+statements, or passed to other procedures that need the connection
+process's id. This also sets the @code{fileid} field in the
+@code{target_info} array.
+
+
+@item remote_close @var{shellid}
+@cindex Closing a remote connection
+@emph{shellid} is value returned by a call to @code{remote_open}. This
+closes the connection to the target so resources can be used by
+others. This parameter can be left off if the @code{fileid} field in the
+@code{target_info} array is set.
+
+@item telnet @var{hostname} @var{port}
+@itemx rlogin @var{hostname}
+@itemx rsh @var{hostname}
+@cindex IP network procedures
+@cindex network (IP) procedures
+@emph{IP network procedures.} @var{hostname} refers to the IP address or
+name (for example, an entry in @file{/etc/hosts}) for this target.  The
+procedure names reflect the Unix utility used to establish a
+connection. The optional @var{port} is used to specify the IP port
+number. The value of the @code{netport} field in the @code{target_info}
+array is used. (was @code{$netport}) This value has two parts, the
+hostname and the port number, seperated by a @emph{:}. If @code{host} or
+@code{target} is used in the @code{hostname} field, than the config
+array is used for all information.
+
+@item tip @var{port}
+@cindex serial line connection, @code{tip}
+@emph{Serial line procedure.} Connect using the Unix utility @code{tip}.
+@var{port} must be a name from the @code{tip} configuration file
+@file{/etc/remote}.  Often, this is called @samp{hardwire}, or something
+like @samp{ttya}. This file holds all the configuration data for
+the serial port. The value of the @code{serial} field in the
+@code{target_info} array is used. (was @code{$serialport}) If
+@code{host} or @code{target} is used in the @code{port} field, than
+the config array is used for all information.
+
+@item kermit @var{port} @var{bps}
+@cindex serial line connection, @code{kermit}
+@emph{Serial line procedure.}  Connect using the program @code{kermit}.
+@var{port} is the device name, e.g. @file{/dev/ttyb}.  @var{bps} is
+the line speed to use (in bits per second) for the connection. The value
+of the @code{serial} field in the @code{target_info} array is used. (was
+@code{$serialport}) If @code{host} or @code{target} is used in the
+@code{port} field, than the config array is used for all information.
+
+@end ftable
+
+@noindent
+@emph{Procedures to manage a connection:}
+
+@ftable @code
+@item tip_download @var{spawnid} @var{file}
+@cindex download, @code{tip}
+@cindex serial download, @code{tip}
+Download @file{@var{file}} to the process @var{spawnid} (the value
+returned when the connection was established), using the @code{~put}
+command under @code{tip}.  Most often used for single board computers
+that require downloading programs in @sc{ascii} S-records.  Returns
+@code{1} if an error occurs, @code{0} otherwise.
+
+@item exit_remote_shell @var{spawnid}
+@cindex terminating remote connection
+@cindex remote connection, ending
+Exits a remote process started by any of the connection procedures.
+@var{spawnid} is the result of the connection procedure that started the
+remote process.
+
+@item download @var{file} @r{[} @var{spawnid} @r{]}
+@cindex download a file
+After you establish a connection to a target, you can download programs
+using this command.  @code{download} reads in @var{file} (object code in
+S-record format) and writes it to the device controlling this
+@var{spawnid}.  (From the point of view of the target, the S-record file
+comes in via standard input.)
+
+If you have more than one target active, you can use the optional argument
+@var{spawnid} to specify an alternative target (the default is the most
+recently established @var{spawnid}.)
+@end ftable
+
+@noindent
+@node utils.exp, target.exp, remote.exp, DejaGnu Builtins
+@subsection Utility Procedures
+
+@kindex utils.exp
+@kindex lib/utils.exp
+@file{lib/utils.exp} defines these utility procedures:
+
+@ftable @code
+@item getdirs @var{dir}
+@itemx getdirs @var{dir} @var{pattern}
+@cindex directories matching a pattern
+@cindex pattern match, directory
+Returns a list of all the directories in the single directory @var{dir}
+that match @var{pattern}.  If you do not specify @var{pattern},
+@code{getdirs} assumes @samp{*}.  You may use the common shell wildcard
+characters in @var{pattern}. If no directories match the pattern, then a
+@code{NULL} string is returned.
+
+@item find @var{dir} @var{pattern}
+@cindex files matching a pattern
+@cindex pattern match, filenames
+Search for files whose names match @var{pattern} (using shell wildcard
+characters for filename expansion).  Search subdirectories recursively,
+starting at @var{dir}.  The result is the list of files whose names
+match; if no files match, the result is empty.  Filenames in the result
+include all intervening subdirectory names. If no files match the
+pattern, then a @code{NULL} string is returned.
+
+@item which @var{binary}
+@cindex path lookup
+Searches the execution path for an executable file @var{binary}, like
+the the BSD @code{which} utility.  This procedure uses the shell
+environment variable @samp{PATH}. It returns @code{0} if the binary is
+not in the path, or if there is no @samp{PATH} environment variable. If
+@var{binary} is in the path, it returns the full path to @var{binary}.
+
+@item grep @var{filename} @var{regexp}
+@item grep @var{filename} @var{regexp} line
+@cindex regular expression, file contents
+@cindex searching file contents
+Search the file called @var{filename} (a fully specified path) for lines
+that contain a match for regular expression @var{regexp}.  The result is
+a list of all the lines that match.  If no lines match, the result is an
+empty string.  Specify @var{regexp} using the standard regular
+expression style used by the Unix utility program @code{grep}.
+
+Use the optional third argument @samp{line} to start lines in the result
+with the line number in @var{filename}.  (This argument is simply an
+option flag; type it just as shown---@samp{line}.)
+
+@item diff @var{filename} @var{filename}
+@cindex finding file differences
+@cindex comparing files
+Compares the two files and returns a 1 if they match, or a 0 if they
+don't. If @code{verbose} is set, then it'll print the differences to the
+screen.
+
+@item slay @var{name}
+@cindex slaying processes
+This look in the process table for @var{name} and send it a unix
+@code{SIGINT}, killing the process.
+
+@item absolute @var{path}
+@cindex converting relative paths to absolute
+This procedure takes the relative @var{path}, and converts it to an
+absolute path.
+
+@item psource @var{filename}
+@cindex sourcing Tcl files
+This sources the file @var{filename}, and traps all errors. It also
+ignores all extraneous output. If there was an error it returns a 1,
+otherwise it returns a 0.
+
+@item prune @var{list} @var{pattern}
+@cindex list, pruning
+Remove elements of the Tcl list @var{list}.  Elements are fields
+delimited by spaces.  The result is a copy of @var{list}, without any
+elements that match @var{pattern}.  You can use the common shell
+wildcard characters to specify @var{pattern}.
+
+@item setenv @var{var} @var{val}
+@cindex setting environment variables
+Sets the variable @var{var} to the value @var{val}.
+
+@item unsetenv @var{var}
+@cindex unsetting environment variables
+Unsets the environment variable @var{var}
+
+@item getenv @var{var}
+@cindex getting environment variables
+returns the value of @var{var} in the environment if it exists,
+otherwise it returns @code{NULL}.
+
+@item runtest_file_p @var{runtests} @var{testcase}
+@cindex selecting a range of tests
+@cindex tests, running specifically
+Search @var{runtests} for @var{testcase} and return 1 if found, 0 if not.
+@var{runtests} is a list of two elements.  The first is the pathname of
+the testsuite expect script running.  The second is a copy of what was
+on the right side of the @code{=} if @samp{foo.exp="@dots{}"} was specified,
+or an empty string if no such argument is present.
+This is used by tools like compilers where each testcase is a file.
+
+@item prune_system_crud @var{system} @var{text}
+@cindex pruning system output, examining program output
+For system @var{system}, delete text the host or target operating system might
+issue that will interfere with pattern matching of program output in
+@var{text}.  An example is the message that is printed if a shared library
+is out of date.
+
+@end ftable
+
+@noindent
+@node target.exp, debugger.exp, utils.exp, DejaGnu Builtins
+@subsection Cross target procedure
+
+@kindex target.exp
+@kindex lib/target.exp
+@file{lib/target.exp} defines these utility procedures:
+
+@ftable @code
+
+@item push_target @emph{name}
+@cindex set current target
+This makes the target named @emph{name} be the current target
+connection. The value of @emph{name} is an index into the
+@code{target_info} array and is set in the global config file.
+
+@item pop_target
+@cindex unset current target
+This unsets the current target connection.
+
+@item list_targets
+@cindex lists supported targets
+This lists all the supported targets for this architecture.
+
+@item push_host @emph{name}
+@cindex set current host
+This makes the host named @emph{name} be the current remote host
+connection. The value of @emph{name} is an index into the
+@code{target_info} array and is set in the global config file.
+
+@item pop_host
+@cindex unset current host
+This unsets the current host connection.
+
+@c @item compile @emph{file}
+@cindex compile a file
+This invokes the compiler as set by @code{CC} to compile the file
+@emph{file}. The default options for many cross compilation targets are
+@emph{guessed} by DejaGnu, and these options can be added to by passing
+in more parameters as arguments to @code{compile}. Optionally, this will
+also use the value of the @code{cflags} field in the target config
+array. If the host is not the same as the build machines, then then
+compiler is run on the remote host using @code{execute_anywhere}.
+
+@c @item archive @emph{file}
+@cindex archive object files
+This produces an archive file. Any parameters passed to @code{archive}
+are used in addition to the default flags. Optionally, this will
+also use the value of the @code{arflags} field in the target config
+array. If the host is not the same as the build machines, then then
+archiver is run on the remote host using @code{execute_anywhere}.
+
+@c @item ranlib @emph{file}
+@cindex ranlib a file
+This generates an index for the archive file for systems that aren't
+POSIX yet. Any parameters passed to @code{ranlib} are used in for the
+flags.
+
+@item execute_anywhere @emph{cmdline}
+@cindex executing commands remotely
+This executes the @emph{cmdline} on the proper host. This should be used
+as a replacement for the Tcl command @code{exec} as this version
+utilizes the target config info to execute this command on the build
+machine or a remote host. All config information for the remote host
+must be setup to have this command work. If this is a canadian cross,
+(where we test a cross compiler that runs on a different host then where
+DejaGnu is running) then a connection is made to the remote host and
+the command is executed there. It returns either @emph{REMOTERROR} (for
+an error) or the output produced when the command was executed. This is
+used for running the tool to be tested, not a test case.
+
+@end ftable
+
+@node debugger.exp, , target.exp, DejaGnu Builtins
+@subsection Debugging Procedures
+
+@kindex debugger.exp
+@kindex lib/debugger.exp
+@file{lib/debugger.exp} defines these utility procedures:
+
+@ftable @code
+
+@item dumpvars @emph{expr}
+@cindex Print global variable values
+This takes a csh style regular expression (glob rules) and prints the
+values of the global variable names that match.  It is abbreviated as
+@code{dv}
+
+@item dumplocals @emph{expr}
+@cindex Print local variable value
+This takes a csh style regular expression (glob rules) and prints the
+values of the local variable names that match. It is abbreviated as
+@code{dl}.
+
+@item dumprocs @emph{expr}
+@cindex Print procedure bodies
+This takes a csh style regular expression (glob rules) and prints the
+body of all procs that match. It is abbreviated as @code{dp}
+
+@item dumpwatch @emph{expr}
+@cindex Print watchpoints
+This takes a csh style regular expression (glob rules) and prints all
+the watchpoints. It is abbreviated as @code{dw}.
+
+@c FIXME: finish these when the code is fixed.
+@c @item watcharray @emph{element} @emph{type}
+@c @cindex Set a watchpoint on an array
+@c This sets an watchpoint of the @emph{element-type} on the 
+@c @item watchvar v null type
+@c @cindex Set a watchpoint on a variable
+
+@item watchunset @emph{var}
+@cindex Watch when a variable is unset
+This breaks program execution when the variable @emph{var} is unset. It
+is abbreviated as @code{wu}.
+
+@item watchwrite @emph{var}
+@cindex Watch when a variable is written
+This breaks program execution when the variable @emph{var} is
+written. It is abbreviated as @code{ww}.
+
+@item watchread @emph{var}
+@cindex Watch when a variable is read
+This breaks program execution when the variable @emph{var} is read. It
+is abbreviated as @code{wr}.
+
+@item watchdel @emph{watch}
+@cindex Delete a watchpoint.
+This deletes a the watchpoint for @emph{watch}. It is abbreviated as
+@code{wd}.
+
+@item print @emph{var}
+@cindex Printing variable values
+This prints the value of the variable @emph{var}. It is abbreviated as
+@code{p}.
+
+@item quit
+@cindex Quiting DejaGnu
+This makes runtest exit. It is abbreviated as @code{q}.
+
+@item bt
+@cindex Print a backtrace
+This prints a backtrace of the executed Tcl commands.
+
+@end ftable
+
+@node Target Dependent
+@section Target dependent procedures
+@cindex target dependent procedures
+
+@c FIXME? These may be renamed to just "start", "load", "exit", and
+@c "version" eventually.
+
+Each combination of target and tool requires some target-dependent
+procedures.  The names of these procedures have a common form: the tool
+name, followed by an underbar @samp{_}, and finally a suffix describing
+the procedure's purpose.  For example, a procedure to extract the
+version from @sc{gdb} is called @samp{gdb_version}.  @xref{Init Module,,
+Initialization Module}, for a discussion of how DejaGnu arranges to find
+the right procedures for each target.
+
+@code{runtest} itself calls only two of these procedures,
+@code{@var{tool}_exit} and @code{@var{tool}_version}; these procedures use
+no arguments.
+
+The other two procedures, @code{@var{tool}_start} and
+@code{@var{tool}_load}, are only called by the test suites themselves
+(or by testsuite-specific initialization code); they may take arguments
+or not, depending on the conventions used within each test suite.
+
+@ftable @code
+@item @var{tool}_start
+@cindex start procedure, tested tools
+Starts a particular tool.  For an interactive tool,
+@code{@var{tool}_start} starts and initializes the tool, leaving the
+tool up and running for the test cases; an example is @code{gdb_start},
+the start function for @sc{gdb}.  For a batch oriented tool,
+@code{@var{tool}_start} is optional; the recommended convention is to
+let @code{@var{tool}_start} run the tool, leaving the output in a
+variable called @code{comp_output}.  Test scripts can then analyze
+@samp{$comp_output} to determine the test results.  An example of this
+second kind of start function is @code{gcc_start}, the start function
+for @sc{gcc}.
+
+@code{runtest} itself @emph{does not call} @code{@var{tool}_start}.  The
+initialization module @file{@var{tool}_init.exp} must call
+@code{@var{tool}_start} for interactive tools; for batch-oriented tools,
+each individual test script calls @code{@var{tool}_start} (or makes
+other arrangements to run the tool).
+
+@item @var{tool}_load
+@cindex load procedure, tested tools
+Loads something into a tool. For an interactive tool, this conditions
+the tool for a particular test case; for example, @code{gdb_load} loads
+a new executable file into the debugger. For batch oriented tools,
+@code{@var{tool}_load} may do nothing---though, for example, the
+@sc{gcc} support uses @code{gcc_load} to load and run a binary on the
+target environment.  Conventionally, @code{@var{tool}_load} leaves the
+output of any program it runs in a variable called @samp{exec_output}.
+Writing @code{@var{tool}_load} can be the most complex part of extending
+DejaGnu to a new tool or a new target, if it requires much communication
+coding or file downloading.
+
+Test scripts call @code{@var{tool}_load}.
+
+@item @var{tool}_exit
+@cindex exit procedure, tested tools
+Cleans up (if necessary) before @code{runtest} exits. For interactive
+tools, this usually ends the interactive session.  You can also use
+@code{@var{tool}_exit} to remove any temporary files left over from the
+tests.
+
+@code{runtest} calls @code{@var{tool}_exit}.
+
+@item @var{tool}_version
+@cindex version procedure, tested tools
+Prints the version label and number for @var{tool}.  This is called by
+the DejaGnu procedure that prints the final summary report.  The output
+should consist of the full path name used for the tested tool, and its
+version number.
+
+@code{runtest} calls @code{@var{tool}_version}.
+@end ftable
+
+The usual convention for return codes from any of these procedures
+(although it is not required by @code{runtest}) is to return @code{0} if
+the procedure succeeded, @code{1} if it failed, and @code{-1} if there
+was a communication error.
+
+@node Cross Targets
+@section Remote targets supported
+
+@cindex targets
+@cindex remote testing
+The DejaGnu distribution includes support for the following remote
+targets.  You can set the target name and the connect mode in the
+@file{site.exp} file (using the Tcl variables @samp{targetname} and
+@samp{connectmode}, respectively), or on the @code{runtest} command line
+(using @samp{--name} and @samp{--connect}).
+
+@table @strong
+@item @sc{amd} 29000, with UDI protocol
+Configure DejaGnu for target @samp{a29k-amd-udi}.  (Cygnus
+@code{configure} also recognizes the abbreviation @samp{udi29k}.)  Then,
+to run tests, use the @code{runtest} target name to specify whether you
+want to use a simulator, or a particular hardware board.  The particular
+string to use with @samp{--name} will depend on your UDI setup file,
+@file{udi_soc} (if @file{udi_soc} is not in your working directory, the
+environment variable @samp{UDICONF} should contain a path to this file).
+For example, if your UDI setup file includes these lines:
+@end table
+@c table "ends" *only* to allow wider example below
+
+@cartouche
+@smallexample
+iss   AF_UNIX  *   isstip -r /home/gnu/29k/src/osboot/sim/osboot
+mon   AF_UNIX  *   montip -t serial -baud 9600 -com /dev/ttyb
+@end smallexample
+@end cartouche
+
+@table @strong
+@item @w{ }
+@c fake out table/item into continuing w/same margin as before
+You can use @samp{--name iss} to run tests on the simulator, and
+@samp{--name mon} to run tests on the 29K hardware.  See the
+manufacturer's manuals for more information on UDI and @file{udi_soc}.
+@c FIXME! Is there a better ref than "the manufacturer's manuals"?
+
+@kindex mondfe
+The default connect protocol is @samp{mondfe} with either back end.
+@code{mondfe} is the only shell DejaGnu supports for UDI targets.
+@code{mondfe} is an @sc{amd} specific monitor program freely available
+from @sc{amd}.
+
+@emph{Warning:} This target requires @sc{gdb} version 4.7.2 (or
+greater).  Earlier versions of @sc{gdb} do not fully support the
+@code{load} command on this target, so DejaGnu has no way to load
+executable files from the debugger.
+
+@item Motorola 680x0 boards, a.out or @sc{coff} object format
+Configure DejaGnu for any remote target matching @samp{m68k-*}.
+
+@emph{Warning:} Most @samp{m68k-*} configurations run all tests only for
+native testing (when the target is the same as the host).  When you
+specify most of these targets for a cross configuration, you will only be
+able to use tests that run completely within the host (for example,
+tests of the binary utilities such as the archiver; or compiler tests
+that only generate code rather than running it).
+
+To run a.out or @sc{coff} binaries on a remote M68K, you must configure
+DejaGnu for a particular target board.  @samp{m68k-abug} is an example.
+(In general for an embedded environment, because it does not have absolute
+addresses, a.out is not a good choice for output format in any case; most
+often S-records or Hex-32 are used instead.)
+
+@item Motorola 68K MVME 135 board running ABug boot monitor
+Configure for @samp{m68k-abug-aout} or @samp{m68k-abug-coff} (as a
+target).  This boot monitor can only download S-records; therefore, the
+DejaGnu tests for this environment require a linker command script to
+convert either output format to S-records, setting the default addresses
+for @code{.text}, @code{.bss}, and @code{.data}.
+
+With this configuration, the default for @samp{--connect} is @samp{tip}.
+@samp{tip} is the only communications protocol supported for connecting
+to @samp{m68k-abug-*} targets.  @samp{tip} uses an @sc{ascii} downloader
+(the @code{~put} command) to load S-records into the target board.  The
+@samp{--name} string must be a machine name that @code{tip}
+understands (for example, on some @code{tip} implementations it must be
+an entry from the initialization file for @code{tip}; this file is
+sometimes called @file{/etc/remote}).
+
+See your system documentation for information on how to create new
+entries in @file{/etc/remote}.  (Some @sc{unix} systems are distributed
+with at least one default entry with a name resembling @samp{hardwire};
+if your system has one, you can edit it, or make a modified copy with a
+new name.)  When you have a working @file{/etc/remote} entry
+@var{abugtarget}, you should be able to type @samp{tip
+@var{abugtarget}}, and get the prompt @samp{135ABUG>} from the board.
+Use the same @var{abugtarget} string with @samp{runtest --name}.
+
+@item Motorola IDP board running the rom68k boot monitor
+@c FIXME 1: this doesn't really say anything!  OK, so functionality is
+@c the same.  Is object code the same (srecords)?  Do we configure with
+@c the same triplets?  What is the default for --connect?  Is
+@c any comms method other than tip supported?  What prompt to expect
+@c when tip connected?
+@c FIXME 2: should @code{BUG} below be @code{ABUG}?
+This is the same in functionality as the MVME board running the
+@code{BUG} boot monitor. Only the monitor commands and the addresses are
+different.
+
+@item VxWorks (Motorola 68K or Intel 960)
+Configure DejaGnu for either @samp{m68k-wrs-vxworks} (abbreviated
+@samp{vxworks68}) or @samp{i960-wrs-vxworks} (abbreviated
+@samp{vxworks960}).  Since both targets support IP addressing, specify
+the network address (for example, a host name from @file{/etc/hosts})
+with @samp{--name}.
+
+The default connect protocol is @samp{rlogin}, but you can use any of
+@samp{--connect rlogin}, @samp{--connect telnet}, or @samp{--connect
+rsh}.
+
+Test scripts need no special code to load programs into these targets;
+since VxWorks supports NFS, all you must do is ensure test programs are
+on an exported filesystem.
+
+@cindex VxWorks, link with @samp{-r}
+When you compile for VxWorks, use the linker @samp{-r} option to make
+the linker output relocatable---at least if you want to use library
+routines. Many standard C routines are included in VxWorks; often no
+additional libraries are needed.  See your VxWorks system documentation
+for additional details.
+@end table
+
+@node Input Files
+@section The files DejaGnu reads
+@cindex input files
+
+The @code{runtest} program used to invoke DejaGnu is a short shell
+script generated by @code{make} during the configuration process.  Its
+main task is to read the main test framework driver, @file{runtest.exp}.
+
+@file{runtest.exp}, in turn, reads @code{expect} code from certain other
+files, in this order:
+
+@enumerate
+@item
+Each of the @file{site.exp} local definition files available.
+@xref{Customizing,,Setting @code{runtest} defaults}, for details.
+
+@item
+@file{lib/utils.exp}, a collection of utility procedures.  @xref{DejaGnu
+Builtins,,DejaGnu Builtins}, for descriptions of these procedures.
+
+@item
+@file{lib/framework.exp}, a file of subroutines meant for @code{runtest}
+itself rather than for general-purpose use in both @code{runtest} and
+test suites.
+
+@item
+@file{debugger.exp}, Don Libes' Tcl Debugger.  (See @cite{A Debugger for
+Tcl Applications} by Don Libes. This paper is distributed with
+@code{expect} in PostScript form as the file
+@file{expect/tcl-debug.ps}.)
+
+@item
+@file{lib/remote.exp}, a collection of subroutines meant for connecting
+to remote machines.
+
+@item
+@file{lib/target.exp}, a collection of subroutines used for the
+configuration systems in DejaGnu. These procedures typically manipulate
+or utilize the configuration system.
+
+@item
+@c FIXME!  A comment in runtest.exp claims a system default is used if
+@c         no tool-specific init file is not available; I couldn't see where
+@c         the program flow actually does this, though---pesch 30jul1993.
+An initialization file @code{@var{tool}_init.exp}.  @xref{Init
+Module,,Initialization module}, for more discussion of init files.
+@end enumerate
+
+@c This hard page break is mainly intended for smallbook formatting;
+@c some examples in this section come out better if this starts at a
+@c page boundary.
+@page
+@node Output Files
+@section The files DejaGnu writes
+@cindex output files
+
+@code{runtest} always writes two kinds of output files: summary logs and
+detailed logs.  The contents of both of these are determined by your
+tests.
+
+For troubleshooting, a third kind of output file is useful: use
+@samp{--debug} to request an output file showing details of what
+@code{expect} is doing internally.
+
+@menu
+* Summary::             Files that summarize tests
+* Detail::              Files that contain complete test results
+* Debug::               Logging expect internal actions
+@end menu
+
+@node Summary
+@subsection Summary log
+@cindex summary log
+
+@code{runtest} always produces a summary output file
+@file{@var{tool}.sum}.  This summary shows the names of all test files
+run; for each test file, one line of output from each @code{pass}
+command (showing status @samp{PASS} or @samp{XPASS}) or @code{fail}
+command (status @samp{FAIL} or @samp{XFAIL}); trailing summary
+statistics that count passing and failing tests (expected and
+unexpected); and the full pathname and version number of the tool
+tested.  (All possible outcomes, and all errors, are always reflected in
+the summary output file, regardless of whether or not you specify
+@samp{--all}.)
+
+If any of your tests use the procedures @code{unresolved},
+@code{unsupported}, or @code{untested}, the summary output also
+tabulates the corresponding outcomes.
+
+For example, after @samp{runtest --tool binutils}, look for a summary
+log in @file{binutils.sum}.  Normally, @code{runtest} writes this file
+in your current working directory; use the @samp{--outdir} option to
+select a different directory.
+
+@need 3500
+@noindent
+Here is a short sample summary log:
+
+@cartouche
+@smallexample
+Test Run By rob on Mon May 25 21:40:57 PDT 1992
+                === gdb tests ===
+Running ./gdb.t00/echo.exp ...
+PASS:   Echo test
+Running ./gdb.all/help.exp ...
+PASS:   help add-symbol-file
+PASS:   help aliases
+PASS:   help breakpoint "bre" abbreviation
+FAIL:   help run "r" abbreviation
+Running ./gdb.t10/crossload.exp ...
+PASS:   m68k-elf (elf-big) explicit format; loaded
+XFAIL:  mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed
+C types 
+                === gdb Summary ===
+# of expected passes 5
+# of expected failures 1
+# of unexpected failures 1
+/usr/latest/bin/gdb version 4.6.5 -q
+@end smallexample
+@end cartouche
+
+@node Detail
+@subsection Detailed log
+@cindex detailed log
+
+@code{runtest} also saves a detailed log file @file{@var{tool}.log},
+showing any output generated by tests as well as the summary output.
+For example, after @samp{runtest --tool binutils}, look for a detailed
+log in @file{binutils.log}.  Normally, @code{runtest} writes this file
+in your current working directory; use the @samp{--outdir} option to
+select a different directory.
+
+@need 4000
+@noindent
+Here is a brief example showing a detailed log for @sc{g++} tests:
+
+@cartouche
+@smallexample
+Test Run By rob on Mon May 25 21:40:43 PDT 1992
+
+                === g++ tests ===
+
+--- Running ./g++.other/t01-1.exp ---
+        PASS:   operate delete
+
+--- Running ./g++.other/t01-2.exp ---
+        FAIL:   i960 bug EOF
+p0000646.C: In function `int  warn_return_1 ()':
+p0000646.C:109: warning: control reaches end of non-void function
+p0000646.C: In function `int  warn_return_arg (int)':
+p0000646.C:117: warning: control reaches end of non-void function
+p0000646.C: In function `int  warn_return_sum (int, int)':
+p0000646.C:125: warning: control reaches end of non-void function
+p0000646.C: In function `struct foo warn_return_foo ()':
+p0000646.C:132: warning: control reaches end of non-void function
+
+--- Running ./g++.other/t01-4.exp ---
+        FAIL:   abort
+900403_04.C:8: zero width for bit-field `foo'
+--- Running ./g++.other/t01-3.exp ---
+        FAIL:   segment violation
+900519_12.C:9: parse error before `;'
+900519_12.C:12: Segmentation violation
+/usr/latest/bin/gcc: Internal compiler error: program cc1plus got
+fatal signal
+
+                === g++ Summary ===
+
+# of expected passes 1
+# of expected failures 3
+/usr/ps/bin/g++ version cygnus-2.0.1
+@end smallexample
+@end cartouche
+
+@node Debug
+@subsection Logging @code{expect} internal actions
+@cindex debug log
+
+With the @samp{--debug} option, you can request a log file showing the
+output from @code{expect} itself, running in debugging mode. This file
+(@file{dbg.log}, in the directory where you start @code{runtest}) shows
+each pattern @code{expect} considers in analyzing test output.
+
+This file reflects each @code{send} command, showing the string sent as
+input to the tool under test; and each @code{expect} command, showing
+each pattern it compares with the tool output.
+
+The log messages for @code{expect} begin with a message of the form
+
+@smallexample
+expect: does @{@var{tool output}@} (spawn_id @var{n}) match pattern
+@{@var{expected pattern}@}?
+@end smallexample
+
+@noindent
+For every unsuccessful match, @code{expect} issues a @samp{no} after
+this message; if other patterns are specified for the same
+@code{expect} command, they are reflected also, but without the first
+part of the message (@samp{expect@dots{}match pattern}).  
+
+When @code{expect} finds a match, the log for the successful match ends
+with @samp{yes}, followed by a record of the @code{expect} variables set
+to describe a successful match.  Here is an excerpt from the debugging
+log for a @sc{gdb} test:
+
+@c FIXME! Why is the second spawn_id shown 0 rather than 6?
+@cartouche
+@smallexample
+send: sent @{break gdbme.c:34\n@} to spawn id 6
+expect: does @{@} (spawn_id 6) match pattern @{Breakpoint.*at.* file
+ gdbme.c, line 34.*\(gdb\) $@}? no
+@{.*\(gdb\) $@}? no
+expect: does @{@} (spawn_id 0) match pattern @{<return>@}? no
+@{\(y or n\) @}? no
+@{buffer_full@}? no
+@{virtual@}? no
+@{memory@}? no
+@{exhausted@}? no
+@{Undefined@}? no
+@{command@}? no
+break gdbme.c:34
+Breakpoint 8 at 0x23d8: file gdbme.c, line 34.
+(gdb) expect: does @{break gdbme.c:34\r\nBreakpoint 8 at 0x23d8: 
+file gdbme.c, line 34.\r\n(gdb) @} (spawn_id 6) match pattern
+@{Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $@}? yes
+expect: set expect_out(0,start) @{18@}
+expect: set expect_out(0,end) @{71@}
+expect: set expect_out(0,string) @{Breakpoint 8 at 0x23d8: file
+gdbme.c, line 34.\r\n(gdb) @}
+expect: set expect_out(spawn_id) @{6@}
+expect: set expect_out(buffer) @{break gdbme.c:34\r\nBreakpoint 8
+at 0x23d8: file gdbme.c, line 34.\r\n(gdb) @}
+        PASS:   70      0       breakpoint line number in file
+@end smallexample
+@end cartouche
+
+@noindent
+This example exhibits three properties of @code{expect} and DejaGnu that
+might be surprising at first glance:
+
+@itemize @bullet
+@item
+Empty output for the first attempted match.  The first set of attempted
+matches shown ran against the output @samp{@{@}}---that is, no output.
+@code{expect} begins attempting to match the patterns supplied
+immediately; often, the first pass is against incomplete output (or
+completely before all output, as in this case).
+
+@item
+Interspersed tool output.  The beginning of the log entry for the second
+attempted match may be hard to spot: this is because the prompt
+@samp{(gdb) } appears on the same line, just before the @samp{expect:}
+that marks the beginning of the log entry.  
+
+@item
+Fail-safe patterns.  Many of the patterns tested are fail-safe patterns
+provided by @sc{gdb} testing utilities, to reduce possible
+indeterminacy.  It is useful to anticipate potential variations
+caused by extreme system conditions (@sc{gdb} might issue the message
+@samp{virtual memory exhausted} in rare circumstances), or by changes in
+the tested program (@samp{Undefined command} is the likeliest outcome if
+the name of a tested command changes).
+
+The pattern @samp{@{<return>@}} is a particularly interesting fail-safe
+to notice; it checks for an unexpected @key{RET} prompt.  This may
+happen, for example, if the tested tool can filter output through a
+pager.
+
+These fail-safe patterns (like the debugging log itself) are primarily
+useful while developing test scripts.  Use the @code{error} procedure to
+make the actions for fail-safe patterns produce messages starting with
+@samp{ERROR} on the @code{runtest} standard output, and in the detailed
+log file.
+@end itemize
+
+@node Tests
+@chapter How To Write a Test Cases
+@cindex writing a test case
+@cindex test case, writing
+
+@menu
+* Writing::                     Writing a test case
+* Debugging::                   Debugging a test case
+* Adding::                      Adding a test case to a test suite
+* Hints::                       Hints on writing a test case
+* Variables::                   Special variables used by test cases
+@end menu
+
+@node Writing
+@section Writing a test case
+
+The easiest way to prepare a new test case is to base it on an existing
+one for a similar situation.  There are two major categories of tests:
+batch or interactive.  Batch oriented tests are usually easier to write.
+
+The @sc{gcc} tests are a good example of batch oriented tests.  All
+@sc{gcc} tests consist primarily of a call to a single common procedure,
+since all the tests either have no output, or only have a few warning
+messages when successfully compiled.  Any non-warning output is a test
+failure.  All the C code needed is kept in the test directory.  The test
+driver, written in @code{expect}, need only get a listing of all the C
+files in the directory, and compile them all using a generic procedure.
+This procedure and a few others supporting for these tests are kept in
+the library module @file{lib/c-torture.exp} in the @sc{gcc} test suite.
+Most tests of this kind use very few @code{expect} features, and are
+coded almost purely in Tcl.
+
+@noindent
+Writing the complete suite of C tests, then, consisted of these steps:
+
+@enumerate
+@item 
+@cindex Granlund, Torbjorn
+@cindex C torture test
+Copying all the C code into the test directory.  These tests were based on
+the C-torture test created by Torbjorn Granlund (on behalf of the Free
+Software Foundation) for @sc{gcc} development.
+
+@item
+Writing (and debugging) the generic @code{expect} procedures for
+compilation.
+
+@item
+Writing the simple test driver: its main task is to search the directory
+(using the Tcl procedure @code{glob} for filename expansion with
+wildcards) and call a Tcl procedure with each filename.  It also checks
+for a few errors from the testing procedure.
+@end enumerate
+
+Testing interactive programs is intrinsically more complex.  Tests for most
+interactive programs require some trial and error before they are complete.
+
+However, some interactive programs can be tested in a simple fashion
+reminiscent of batch tests.  For example, prior to the creation of
+DejaGnu, the @sc{gdb} distribution already included a wide-ranging
+testing procedure.  This procedure was very robust, and had already
+undergone much more debugging and error checking than many recent
+DejaGnu test cases.  Accordingly, the best approach was simply to
+encapsulate the existing @sc{gdb} tests, for reporting purposes.
+Thereafter, new @sc{gdb} tests built up a family of @code{expect}
+procedures specialized for @sc{gdb} testing.
+
+@file{gdb.t10/crossload.exp} is a good example of an interactive test.
+@c FIXME!  Check what *kind* of example it is---work-intensive, or generic...
+
+@node Debugging
+@section Debugging a test case
+@cindex debugging a test case
+@cindex test case, debugging
+
+@noindent
+These are the kinds of debugging information available from DejaGnu:
+
+@enumerate
+@item
+Output controlled by test scripts themselves, explicitly allowed for by
+the test author.  This kind of debugging output appears in the detailed
+output recorded in the @file{@var{tool}.log} file.  To do the same for
+new tests, use the @code{verbose} procedure (which in turn uses the
+variable also called @code{verbose}) to control how much output to
+generate.  This will make it easier for other people running the test to
+debug it if necessary.  Whenever possible, if @samp{$verbose} is
+@code{0}, there should be no output other than the output from
+@code{pass}, @code{fail}, @code{error}, and @code{warning}.  Then, to
+whatever extent is appropriate for the particular test, allow
+successively higher values of @samp{$verbose} to generate more
+information.  Be kind to other programmers who use your tests: provide
+for a lot of debugging information.
+
+@item
+Output from the internal debugging functions of Tcl and @code{expect}.
+There is a command line options for each; both forms of debugging output
+are recorded in the file @code{dbg.log} in the current directory.
+
+Use @samp{--debug} for information from the @code{expect} level; it
+generates displays of the @code{expect} attempts to match the tool
+output with the patterns specified (@pxref{Debug,,Debug Log}).  This
+output can be very helpful while developing test scripts, since it shows
+precisely the characters received.  Iterating between the latest attempt
+at a new test script and the corresponding @file{dbg.log} can allow you
+to create the final patterns by ``cut and paste''.  This is sometimes
+the best way to write a test case.
+
+Use @samp{--strace} to see more detail at the Tcl level; this shows how Tcl
+procedure definitions expand, as they execute.  The associated number
+controls the depth of definitions expanded; see the discussion of
+@samp{--strace} in @ref{Invoking runtest,,Running the Tests}.
+
+@item
+Finally, if the value of @samp{verbose} is 3 or greater, @code{runtest}
+turns on the @code{expect} command @code{log_user}.  This command prints
+all @code{expect} actions to the @code{expect} standard output, to the
+detailed log file, and (if @samp{--debug} is on) to @file{dbg.log}.
+@end enumerate
+
+@node Adding
+@section Adding a test case to a test suite
+@cindex adding a test case
+
+There are two slightly different ways to add a test case. One is to add
+the test case to an existing directory. The other is to create a new
+directory to hold your test. The existing test directories represent
+several styles of testing, all of which are slightly different; examine
+the directories for the tool of interest to see which (if any) is most
+suitable.
+
+Adding a @sc{gcc} test can be very simple: just add the C code to any
+directory beginning with @samp{gcc.} and it runs on the next
+@samp{runtest --tool gcc}.
+
+To add a test to @sc{gdb}, first add any source code you will need to
+the test directory. Then you can either create a new @code{expect} file,
+or add your test to an existing one (any file with a @samp{.exp}
+suffix).  Creating a new @samp{.exp} file is probably a better idea if
+the test is significantly different from existing tests. Adding it as a
+separate file also makes upgrading easier. If the C code has to be
+already compiled before the test will run, then you'll have to add it to
+the @file{Makefile.in} file for that test directory, then run
+@code{configure} and @code{make}.
+
+Adding a test by creating a new directory is very similar:
+
+@enumerate
+@item
+Create the new directory. All subdirectory names begin with the name of
+the tool to test; e.g. @sc{g++} tests might be in a directory called
+@file{g++.other}. There can be multiple test directories that start with
+the same tool name (such as @samp{g++}).
+
+@item
+Add the new directory name to the @samp{configdirs} definition in the
+@file{configure.in} file for the test suite directory. This way when
+@code{make} and @code{configure} next run, they include the new directory.
+
+@item
+Add the new test case to the directory, as above. 
+
+@item
+To add support in the new directory for configure and make, you must
+also create a @code{Makefile.in} and a @code{configure.in}.  @xref{What
+Configure Does,,What Configure Does, configure.info, Cygnus Configure}.
+@end enumerate
+
+@c FIXME! Expand this sentence to at least a section, maybe a chapter...
+@c The @file{admin} directory contains templates for a few common forms
+@c of test.
+
+@node Hints
+@section Hints on writing a test case
+@cindex hints on test case writing
+
+There may be useful existing procedures already written for your test in
+the @file{lib} directory of the DejaGnu distribution.  @xref{DejaGnu
+Builtins,,DejaGnu Builtins}.
+
+It is safest to write patterns that match @emph{all} the output
+generated by the tested program; this is called @dfn{closure}.  If a
+pattern does not match the entire output, any output that remains will
+be examined by the @emph{next} @code{expect} command.  In this
+situation, the precise boundary that determines which @code{expect}
+command sees what is very sensitive to timing between the @code{expect}
+task and the task running the tested tool.  As a result, the test may
+sometimes appear to work, but is likely to have unpredictable results.
+(This problem is particularly likely for interactive tools, but can also
+affect batch tools---especially for tests that take a long time to finish.)
+The best way to ensure closure is to use the @samp{-re} option for the
+@code{expect} command to write the pattern as a full regular
+expressions; then you can match the end of output using a @samp{$}.  It
+is also a good idea to write patterns that match all available output by
+using @samp{.*\} after the text of interest; this will also match any
+intervening blank lines.  Sometimes an alternative is to match end of
+line using @samp{\r} or @samp{\n}, but this is usually too dependent on
+terminal settings.
+@c FIXME!! explain what "end of output" means for interactive task.
+@c (Timeout or EOF, right?)
+
+Always escape punctuation, such as @samp{(} or @samp{"}, in your
+patterns; for example, write @samp{\(}.  If you forget to escape
+punctuation, you will usually see an error message like @samp{extra
+characters after close-quote}.
+
+If you have trouble understanding why a pattern does not match the
+program output, try using the @samp{--debug} option to @code{runtest},
+and examine the debug log carefully.  @xref{Debug,,Debug Log}.  
+
+Be careful not to neglect output generated by setup rather than by the
+interesting parts of a test case.  For example, while testing @sc{gdb},
+I issue a send @samp{set height 0\n} command.  The purpose is simply to
+make sure @sc{gdb} never calls a paging program.  The @samp{set height}
+command in @sc{gdb} does not generate any output; but running @emph{any}
+command makes @sc{gdb} issue a new @samp{(gdb) } prompt.  If there were
+no @code{expect} command to match this prompt, the output @samp{(gdb) }
+begins the text seen by the next @code{expect} command---which might
+make @emph{that} pattern fail to match.
+
+To preserve basic sanity, I also recommended that no test ever pass if
+there was any kind of problem in the test case.  To take an extreme
+case, tests that pass even when the tool will not spawn are misleading.
+Ideally, a test in this sort of situation should not fail either.
+Instead, print an error message by calling one of the DejaGnu procedures
+@code{error} or @code{warning}.
+
+@node Variables
+@section Special variables used by test cases
+@cindex special variables
+
+@cindex variables for all tests
+Your test cases can use these variables, with conventional meanings (as
+well as the variables saved in @file{site.exp}
+@pxref{Customizing,,Setting @code{runtest} defaults}):
+
+@quotation
+@emph{These variables are available to all test cases.}
+@end quotation
+
+@ftable @code
+@item prms_id
+@cindex PRMS bug number
+@cindex GNATS bug number
+@cindex bug number
+The tracking system (e.g. @sc{gnats}) number identifying a corresponding
+bugreport.  (@samp{0} if you do not specify it in the test script.)
+
+@item bug_id
+@cindex bug number, extra
+An optional bug id; may reflect a bug identification from another
+organization.  (@samp{0} if you do not specify it.)
+
+@item subdir
+@cindex current test subdirectory
+The subdirectory for the current test case.
+@end ftable
+
+@quotation
+@emph{These variables should never be changed. They appear in most
+tests.}
+@end quotation
+
+@ftable @code
+@item expect_out(buffer)
+@cindex last command output
+The output from the last command. This is an internal variable set by
+@code{expect}. 
+
+@item exec_output
+This is the output from a @code{@var{tool}_load} command. This only
+applies to tools like @sc{gcc} and @sc{gas} which produce an object
+file that must in turn be executed to complete a test.
+
+@item comp_output
+This is the output from a @code{@var{tool}_start} command.  This is
+conventionally used for batch oriented programs, like @sc{gcc} and
+@sc{gas}, that may produce interesting output (warnings, errors) without
+further interaction.
+@end ftable
+
+@node Extending
+@chapter New Tools, Targets, or Hosts 
+
+The most common ways to extend the DejaGnu framework are: adding a suite
+of tests for a new tool to be tested; adding support for testing on a
+new target; and porting @code{runtest} to a new host.
+
+@menu
+* Adding Tools::                How to add tests for a new tool
+* Adding Targets::              How to add a new target
+* Porting::                     Porting DejaGnu to a new host
+@end menu
+
+@node Adding Tools
+@section Writing tests for a new tool
+
+In general, the best way to learn how to write (code or even prose) is
+to read something similar.  This principle applies to test cases and to
+test suites.  Unfortunately, well-established test suites have a way of
+developing their own conventions: as test writers become more
+experienced with DejaGnu and with Tcl, they accumulate more utilities,
+and take advantage of more and more features of @code{expect} and Tcl in
+general.
+
+Inspecting such established test suites may make the prospect of
+creating an entirely new test suite appear overwhelming.  Nevertheless,
+it is quite straightforward to get a new test suite going.
+
+@cindex Lupton, Robert
+There is one test suite that is guaranteed not to grow more elaborate
+over time: both it and the tool it tests were created expressly to
+illustrate what it takes to get started with DejaGnu.  The
+@file{example/} directory of the DejaGnu distribution contains both an
+interactive tool called @code{calc}, and a test suite for it.  Reading
+this test suite, and experimenting with it, is a good way to supplement
+the information in this section.  (Thanks to Robert Lupton for creating
+@code{calc} and its test suite---and also the first version of this
+section of the manual!)
+
+To help orient you further in this task, here is an outline of the steps
+to begin building a test suite for a program @var{example}.
+
+@enumerate
+@item
+Create or select a directory to contain your new collection of tests.
+Change to that directory (shown here as @code{testsuite}):
+
+@example
+eg$ cd testsuite/
+@end example
+
+@item
+Create a @file{configure.in} file in this directory, to control
+configuration-dependent choices for your tests.  So far as DejaGnu is
+concerned, the important thing is to set a value for the variable
+@code{target_abbrev}; this value is the link to the init file you will
+write soon.  (For simplicity, we assume the environment is Unix, and use
+@samp{unix} as the value.)
+
+What else is needed in @file{configure.in} depends on the requirements
+of your tool, your intended test environments, and which
+@code{configure} system you use.  This example is a minimal
+@code{configure.in} for use with Cygnus Configure.  (For an alternative
+based on the FSF @code{autoconf} system, see the @code{calc} example
+distributed with DejaGnu.)  Replace @var{example} with the name of your
+program:
+
+@cartouche
+@smallexample
+# This file is a shell script fragment
+# for use with Cygnus configure.
+
+srctrigger="@var{example}.0"
+srcname="The DejaGnu @var{example} tests"
+
+# per-host:
+
+# per-target:
+
+# everything defaults to unix for a target
+target_abbrev=unix
+
+# post-target:
+
+@end smallexample
+@end cartouche
+
+@item
+Create @file{Makefile.in}, the source file used by @code{configure} to
+build your @file{Makefile}.  Its leading section should as usual contain
+the values that @code{configure} may override:
+
+@cartouche
+@smallexample
+srcdir = .
+prefix = /usr/local
+
+exec_prefix = $(prefix)
+bindir = $(exec_prefix)/bin
+libdir = $(exec_prefix)/lib
+tooldir = $(libdir)/$(target_alias)
+
+datadir = $(exec_prefix)/lib/dejagnu
+
+RUNTEST = runtest
+RUNTESTFLAGS =
+FLAGS_TO_PASS =
+
+#### host, target, site specific Makefile frags come in here.
+@end smallexample
+@end cartouche
+
+This should be followed by the standard targets at your site.  To begin
+with, they need not do anything---for example, these definitions will
+do:
+
+@cartouche
+@smallexample
+
+all:
+
+info:
+
+install-info:
+
+install:
+uninstall:
+
+clean:
+        -rm -f *~ core *.info*
+
+@end smallexample
+@end cartouche
+
+It is also a good idea to make sure your @file{Makefile} can rebuild
+itself if @file{Makefile.in} changes, with a target like this (which
+works for either Cygnus or FSF Configure):
+
+@cartouche
+@smallexample
+Makefile : $(srcdir)/Makefile.in $(host_makefile_frag) \
+             $(target_makefile_frag)
+        $(SHELL) ./config.status
+@end smallexample
+@end cartouche
+
+You also need to include two targets important to DejaGnu: @code{check},
+to run the tests, and @code{site.exp}, to set up the Tcl copies of
+configuration-dependent values.  The @code{check} target must run
+@samp{runtest --tool @var{example}}:
+
+@cartouche
+@smallexample
+check: site.exp all
+        $(RUNTEST) $(RUNTESTFLAGS) $(FLAGS_TO_PASS) \
+            --tool @var{example} --srcdir $(srcdir) 
+@end smallexample
+@end cartouche
+
+The @code{site.exp} target should usually set up (among other things!) a
+Tcl variable for the name of your program:
+
+@cartouche
+@smallexample
+site.exp: ./config.status Makefile
+        @@echo "Making a new config file..."
+        -@@rm -f ./tmp?
+        @@touch site.exp
+
+        -@@mv site.exp site.bak
+        @@echo "## these variables are automatically\
+ generated by make ##" > ./tmp0
+        @@echo "# Do not edit here. If you wish to\
+ override these values" >> ./tmp0
+        @@echo "# add them to the last section" >> ./tmp0
+        @@echo "set host_os $@{host_os@}" >> ./tmp0
+        @@echo "set host_alias $@{host_alias@}" >> ./tmp0
+        @@echo "set host_cpu $@{host_cpu@}" >> ./tmp0
+        @@echo "set host_vendor $@{host_vendor@}" >> ./tmp0
+        @@echo "set target_os $@{target_os@}" >> ./tmp0
+        @@echo "set target_alias $@{target_alias@}" >> ./tmp0
+        @@echo "set target_cpu $@{target_cpu@}" >> ./tmp0
+        @@echo "set target_vendor $@{target_vendor@}" >> ./tmp0
+        @@echo "set host_triplet $@{host_canonical@}" >> ./tmp0
+        @@echo "set target_triplet $@{target_canonical@}">>./tmp0
+        @@echo "set tool binutils" >> ./tmp0
+        @@echo "set srcdir $@{srcdir@}" >> ./tmp0
+        @@echo "set objdir `pwd`" >> ./tmp0
+        @@echo "set @var{examplename} @var{example}" >> ./tmp0
+        @@echo "## All variables above are generated by\
+ configure. Do Not Edit ##" >> ./tmp0
+                @@cat ./tmp0 > site.exp
+        @@sed < site.bak \
+               -e '1,/^## All variables above are.*##/ d' \
+               >> site.exp
+        -@@rm -f ./tmp?
+@end smallexample
+@end cartouche
+
+@item
+Create a directory (in @file{testsuite/}) called @file{config/}:
+
+@example
+eg$ mkdir config
+@end example
+
+@item
+Make an init file in this directory; its name must start with the
+@code{target_abbrev} value, so call it @file{config/unix.exp}.  
+This is the file that contains the target-dependent procedures;
+fortunately, most of them do not have to do very much in order for
+@code{runtest} to run.
+
+If @var{example} is not interactive, you can get away with this minimal
+@file{unix.exp} to begin with:
+
+@cartouche
+@smallexample
+proc foo_exit @{@} @{@}
+proc foo_version @{@} @{@}
+@end smallexample
+@end cartouche
+
+If @var{example} is interactive, however, you might as well define a
+start routine @emph{and invoke it} by using an init file like this:
+
+@cartouche
+@smallexample
+proc foo_exit @{@} @{@}
+proc foo_version @{@} @{@}
+
+proc foo_start @{@} @{
+  global @var{examplename}
+  spawn $@var{examplename}
+  expect @{
+    -re "" @{@}
+  @}
+@}
+foo_start
+@end smallexample
+@end cartouche
+
+@item
+Create a directory whose name begins with your tool's name, to contain
+tests:
+
+@example
+eg$ mkdir @var{example}.0
+@end example
+
+@item
+Create a sample test file in @file{@var{example}.0}.  Its name must end
+with @samp{.exp}; you can use @samp{first-try.exp}  To begin with, just
+write there a line of Tcl code to issue a message:
+
+@cartouche
+@smallexample
+send_user "Testing: one, two...\n"
+@end smallexample
+@end cartouche
+
+@item
+Back in the @file{testsuite/} (top level) directory, run
+
+@example
+eg$ configure
+@end example
+
+(You may have to specify more of a path, if a suitable @code{configure}
+is not available in your execution path.)
+
+@item
+You are now ready to triumphantly type @samp{make check} or
+@samp{runtest --tool @var{example}}.  You should see something like this:
+
+@cartouche
+@smallexample
+Test Run By rhl on Fri Jan 29 16:25:44 EST 1993
+
+                === @var{example} tests ===
+
+Running ./@var{example}.0/first-try.exp ...
+Testing: one, two...
+
+                === @var{example} Summary ===
+
+@end smallexample
+@end cartouche
+
+There is no output in the summary, because so far the example does not
+call any of the procedures that establish a test outcome.
+
+@item
+Begin writing some real tests.  For an interactive tool, you should
+probably write a real exit routine in fairly short order; in any case,
+you should also write a real version routine soon.
+@end enumerate
+
+@node Adding Targets
+@section Adding a target
+@cindex adding a target
+
+DejaGnu has some additional requirements for target support, beyond the
+general-purpose provisions of Cygnus @code{configure}.  @code{runtest}
+must actively communicate with the target, rather than simply generating
+or managing code for the target architecture.  Therefore, each tool
+requires an initialization module for each target.  For new targets, you
+must supply a few Tcl procedures to adapt DejaGnu to the target.  This
+permits DejaGnu itself to remain target independent.  @xref{Init
+Module,,Initialization module}, for a discussion of the naming
+conventions that enable DejaGnu to locate and use init files.
+
+Usually the best way to write a new initialization module is to edit an
+existing initialization module; some trial and error will be required.
+If necessary, you can use the @samp{--debug} option to see what
+is really going on.
+
+When you code an initialization module, be generous in printing
+information controlled by the @code{verbose} procedure (@pxref{DejaGnu
+Builtins, DejaGnu procedures}).
+
+Most of the work is in getting the communications right. Communications
+code (for several situations involving IP networks or serial lines) is
+available in a DejaGnu library file, @file{lib/remote.exp}.
+@xref{DejaGnu Builtins,,DejaGnu Builtins}. 
+
+@c FIXME!  Say something about Tcl debugger here.
+If you suspect a communication problem, try running the connection
+interactively from @code{expect}.  (There are three ways of running
+@code{expect} as an interactive interpreter.  You can run @code{expect}
+with no arguments, and control it completely interactively; or you can
+use @samp{expect -i} together with other command-line options and
+arguments; or you can run the command @code{interpreter} from any
+@code{expect} procedure.  Use @code{return} to get back to the calling
+procedure (if any), or @code{return -tcl} to make the calling procedure
+itself return to its caller; use @code{exit} or end-of-file to leave
+@code{expect} altogether.)  Run the program whose name is recorded in
+@samp{$connectmode}, with the arguments in @samp{$targetname}, to
+establish a connection.  You should at least be able to get a prompt
+from any target that is physically connected.
+
+@node Porting
+@section Porting to a new host
+@cindex porting to a new host
+
+The task of porting DejaGnu is basically that of porting Tcl and
+@code{expect}. Tcl and @code{expect}, as distributed with DejaGnu, both
+use @code{autoconf}; they should port automatically to most Unix
+systems.
+
+Once Tcl and @code{expect} are ported, DejaGnu should run.  Most system
+dependencies are taken care of by using @code{expect} as the main
+command shell.
+
+@node Installation
+@appendix Installing DejaGnu
+
+@cindex host, explained
+@cindex target, explained
+@cindex DejaGnu configuration
+@cindex configuring DejaGnu
+Once you have the DejaGnu source unpacked and available, you must first
+configure the software to specify where it is to run (and the associated
+defaults); then you can proceed to installing it.
+
+@menu
+* Configuring DejaGnu::
+* Installing DejaGnu::
+@end menu
+
+@node Configuring DejaGnu
+@section Configuring the DejaGnu test driver
+
+It is usually best to configure in a directory separate
+from the source tree, specifying where to find the source with the
+optional @samp{--srcdir} option to @code{configure}. DejaGnu uses the
+GNU @code{autoconf} to configure itself. For more info on using
+autoconf, read the GNU autoconf manual. To configure, execute the
+@file{configure} program, no other options are required. For an example,
+to configure in a seperate tree for objects, execute the configure
+script from the source tree like this:
+
+@smallexample
+../dejagnu-1.3/configure
+@end smallexample
+
+DejaGnu doesn't care at config time if it's for testing a native system
+or a cross system. That is determined at runtime by using the config
+files.
+
+@cindex @code{prefix}, configure options
+@cindex @code{exec_prefix}, configure options.
+You may also want to use the @code{configure} option @samp{--prefix} to
+specify where you want DejaGnu and its supporting code installed.  By
+default, installation is in subdirectories of @file{/usr/local}, but you
+can select any alternate directory @var{altdir} by including
+@samp{--prefix=@var{altdir}} on the @code{configure} command line.
+(This value is captured in the Makefile variables @code{prefix}
+and @code{exec_prefix}.)
+
+@cindex auxiliary programs
+@cindex test suite distributions
+@cindex @code{make} builds part of tests
+Save for a small number of example tests, the DejaGnu distribution
+itself does not include any test suites; these are available separately.
+Test suites for the @sc{gnu} compiler (testing both GCC and G++) and for
+the @sc{gnu} binary utilities are distributed in parallel with the
+DejaGnu distribution (but packaged as separate files).  The test suite
+for the @sc{gnu} debugger is distributed in parallel with each release
+of GDB itself, starting with GDB 4.9.  After configuring the top-level
+DejaGnu directory, unpack and configure the test directories for the
+tools you want to test; then, in each test directory, run @code{make} to
+build auxiliary programs required by some of the tests.
+
+@node Installing DejaGnu
+@section Installing DejaGnu
+
+@cindex installing DejaGnu
+To install DejaGnu in your filesystem (either in @file{/usr/local}, or
+as specified by your @samp{--prefix} option to @code{configure}), execute
+
+@example
+eg$ make install
+@end example
+
+@noindent
+@samp{make install} does these things for DejaGnu:
+
+@enumerate
+@item
+Look in the path specified for executables (@file{$exec_prefix}) for
+directories called @file{lib} and @file{bin}.  If these directories do
+not exist, @samp{make install} creates them.
+
+@item
+Create another directory in the @file{lib} directory, called
+@file{dejagnu}.
+
+@item
+Copy the @code{runtest} shell script into @file{$exec_prefix/bin}.
+
+@item
+Copy all the library files (used to support the framework) into
+@file{$exec_prefix/lib/dejagnu}.
+
+@item
+Copy @file{runtest.exp} into @file{$exec_prefix/lib/dejagnu}.  This is
+the main Tcl code implementing DejaGnu.
+
+@end enumerate
+
+Each test suite collection comes with simple installation instructions
+in a @file{README} file; in general, the test suites are designed to be
+unpacked in the source directory for the corresponding tool, and extract
+into a directory called @file{testsuite}.
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@contents
+
+@bye
diff --git a/doc/overview.sgml b/doc/overview.sgml
new file mode 100644
index 0000000..58bce0c
--- /dev/null
+++ b/doc/overview.sgml
@@ -0,0 +1,439 @@
+<!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+
+<!-- Begin Document Specific Declarations -->
+
+<?Fm: Validation Off>
+
+<!ENTITY version "0.5">
+<!ENTITY dj "DejaGnu">
+
+<!ENTITY dejagnu-copyright "
+	<YEAR>1998</YEAR>
+	<HOLDER>Free Software Foundation, Inc.</HOLDER>">
+
+<!ENTITY dejagnu-code-copyright "
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+This file documents the GNU Testing Framework ``DejaGnu''
+
+Copyright (C) 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
+
+This text may be freely distributed under the terms of the GNU
+General Public License.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+">
+
+<!ENTITY dejagnu-copyright "
+Copyright 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+">
+
+<!-- The reference material -->
+<!entity ref SYSTEM "ref.sgml">
+
+<!-- The user manual -->
+<!entity user SYSTEM "user.sgml">
+
+<!-- End Document Specific Declarations -->
+]>
+
+<book>
+  <bookinfo>
+    <title>&dj;</title>
+    <subtitle>The GNU Testing Framework</subtitle>
+    <date>1998 Nov 24</date>
+    <edition> &version</edition>
+    <releaseinfo> for circulation within Cygnus</releaseinfo>
+    <authorgroup>
+      <author>
+        <firstname>Rob Savoye</firstname>
+        <affiliation>
+          <orgname>Free Software Foundation</orgname></affiliation>
+        <!-- <authorblurb>
+          <title>Rob Savoye</title>
+          <para>
+            His home page is at <ulink>
+            URL="http://www.welcomehome.org/rob.html">this
+            location</ulink>
+            </para>
+        </authorblurb>
+        -->
+      </author>
+    </authorgroup>
+    <address>
+      <email>rob@welcomehome.org</email>
+    </address>
+    <!-- &cygnus-street-address; -->
+    <copyright>&dejagnu-copyright;</copyright>
+    <!-- <legalnotice>
+      <para> -->
+        <!-- [FIXME: must put legal notice here] -->
+      <!-- </para> -->
+      <!-- &cygnus-legal-notice; -->
+    <!-- </legalnotice> -->
+    <revhistory>
+      <revision>
+        <revnumber> 0.1</revnumber>
+        <date>1998-11</date>
+        <authorinitials>rob@welcomehome.org</authorinitials>
+        <revremark>Initial version after conversion to DocBook.</revremark>
+      </revision>
+    </revhistory>
+
+  </bookinfo>
+
+  <toc></toc>
+
+  <preface id=preface>
+    <title>Abstract</title>
+
+    <para>This document attempts to describe the functionality of
+    DejaGnu, the GNU Testing Framework. DejaGnu is entirely written in
+    <productname>Expect</productname>, which uses
+    <productname>Tcl</productname> as a command
+    language. <productname>Expect</productname> serves as a very
+    programmable shell; you can run any program, as with the usual
+    Unix command shells---but once the program is started, your
+    test script has fully programmable control of
+    its input and output.  This does not just apply to the programs
+    under test; <command>expect</command> can also run any auxiliary
+    program, such as <command>diff</command> or <command>sh</command>,
+    with full control over its input and output.</para>  
+
+    <para>DejaGnu itself is merely a framework for creation of a test
+    suites. Test suites are distributed separately for each GNU
+    tool.</para>
+
+  </preface>
+
+  <chapter id=overview xreflabel=Overview>
+    <title>Overview</title>
+
+    <sect1 id=whatis xreflabel="What is &dj; ?">
+      <title>What is &dj; ?</title>
+
+    <para><productname>DejaGnu</productname> is a framework for
+	testing other programs.  Its purpose is to provide a single
+	front end for all tests. Think of it as a custom library of
+	Tcl procedures crafted to support writing a test harness. A
+	<emphasis>Test Harness</emphasis> is the testing
+	infrastructure that is created to support a specific program
+	or tool. Each program can have multiple test suites, all
+	supported by a single test harness. DejaGnu is written in
+	<productname>Expect</productname>, which in turn uses
+	<productname>Tcl</productname> -- Tool command
+	language. There is more information on Tcl at the <ulink
+	URL="http://www.scriptics.com">Scriptics</ulink> web site, and the
+	Expect web site is at <ulink
+	URL="http://expect.nist.gov">NIST</ulink>.</para>
+
+	<para>DejaGnu offers several advantages for testing:</para>
+
+    <itemizedlist mark="bullet" spacing="compact">
+
+      <listitem><para>The flexibility and consistency of the DejaGnu
+	framework make it easy to write tests for any program, with
+	either batch oriented, or interactive programs.</para>
+      </listitem>
+
+      <listitem><para>DejaGnu provides a layer of abstraction which
+	allows you to write tests that are portable to any host or
+	target where a program must be tested. For instance, a test
+	for <command>GDB</command> can run (from any Unix
+	based host) on any target architecture that DejaGnu
+	supports. Currently DejaGnu runs tests on many single board
+	computers, whose operating software ranges from just a boot
+	monitor to a full-fledged, Unix-like realtime OS.</para>
+      </listitem>
+
+      <listitem><para>All tests have the same output format. This
+	makes it easy to integrate testing into other software
+	development processes. DejaGnu's output is designed to be
+	parsed by other filtering script, and it is also human
+	readable.</para>
+      </listitem>
+
+      <listitem><para>Using Tcl and expect, it's easy to create wrappers
+      for existing test suites. By incorporating existing tests under
+      DejaGnu, it's easier to have a single set of report analyse
+      programs..</para>
+
+      </listitem>
+    </itemizedlist>
+
+    <para>Running tests requires two things: the testing framework, and
+    the test suites themselves. Tests are usually written in
+    <productname>Expect</productname> using Tcl, but you can also use a
+    Tcl script to run a test suite that is not based on
+    <productname>Expect</productname>.
+    (<productname>expect</productname> script filenames conventionally
+    use <emphasis>.exp</emphasis> as a suffix; for example, the main
+    implementation of the DejaGnu test driver is in the file
+    <productname>runtest.exp</productname>.)</para>
+	
+    <para>Julia Menapace first coined the term ``Deja Gnu'' to describe an
+    earlier testing framework at Cygnus Support she had written for
+    <command>GDB</command>. When we replaced it with the Expect-based
+    framework, it was like DejaGnu all over again... But more importantly, it
+    was also named after my daughter,<ulink
+    URL="mailto:deja@welcomehome.org">Deja Snow Savoye</ulink> (now 9
+    years old in Dec of 1998), who was a toddler during DejaGnu's
+    creation.</para>
+
+  </sect1>
+
+  <sect1 id=new xreflabel="Release Notes">
+    <title>What's New In This Release</title>
+  
+    <para>This release has a number of substantial changes over version
+    1.3. The most visible change is that the version of Expect and Tcl
+    included in the release are up-to-date with the current stable net
+    releases. The biggest change is years of modifications to the
+    target configuration system, used for cross testing. While this
+    greatly improved cross testing, is has made that subsystem very
+    complicated. The goal is to have this entirely rewritten using
+    <productname>iTcl</productname> by the next release. Other changes
+    are:</para>
+
+    <itemizedlist>
+      <listitem><para>More builtin support for building target binaries
+        with the correct linker flags. Currently this only works with
+        <productname>GCC</productname> as the cross compiler,
+	preferably with a target supported by
+	<xref linkend=libgloss>.</para></listitem>
+
+      <listitem><para>Lots of little bug fixes from years of heavy
+        use at Cygnus Solutions.</para></listitem>
+
+      <listitem><para>DejaGnu now uses
+      <productname>Automake</productname> for Makefile
+      configuration.</para></listitem>
+
+      <listitem><para>Updated documentation, now in SGML
+	(using the <ulink
+	URL="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">free
+	GNU DocBook tools</ulink>) format.</para></listitem>
+	
+      <listitem><para>NT support. There is beta level support for NT
+      that is still a work in progress. This requires the <ulink
+      URL=httpd://sourceware.cygnus.com>Cygwin</ulink> POSIX system
+      for NT.</para></listitem>
+
+    </itemizedlist>
+
+    <sect2 id=cygwin xreflabel="NT Support">
+      <title>NT Support</title>
+  
+      <para>To use DejaGnu on NT, you need to first install the
+	<ulink URL="http://sourceware.cygnus.com">Cygwin</ulink>
+	release. This works as of the B20.1 release. Cygwin is a POSIX
+	system for NT. This covers both utility programs, and a libray
+	that adds POSIX system calls to NT. Among them is pseudo tty
+	support for NT that emulates the POSIX pty standard. The
+	latest Cygwin is always available from <ulink
+	URL="http://sourceware.cygnus.com">this location</ulink>. This
+	works well enough to run <emphasis>"make check"</emphasis> of
+	the GNU development tree on NT after a native build. But the
+	nature of pty's on NT is still evolving. Your mileage may
+	vary...</para>
+
+    </sect2>
+	
+  </sect1>
+
+  <sect1 id=designgoals xreflabel="Design Goals">
+    <title>Design Goals</title>
+
+    <para>DejaGnu grew out of the internal needs of Cygnus Solutions. (then
+    Cygnus Support). Cygnus maintains and enhances a variety of free programs
+    in many different environments, and we needed a testing tool that:</para>
+
+    <itemizedlist mark="bullet">
+      <listitem><para>is useful to developers while fixing bugs.</para>
+      <listitem><para>automates running many tests during a software
+      release process.</para> 
+      <listitem><para>is portable among a variety of host
+      computers.</para> 
+      <listitem><para>supports cross-development testing.</para> 
+      <listitem><para>permits testing interactive programs, like
+      <command>GDB</command>; and </para>
+      <listitem><para>permits testing batch oriented programs, like
+      <command>GCC</command>.</para>
+    </itemizedlist>
+
+    <para>Some of the requirements proved challenging.  For example,
+    interactive programs do not lend themselves very well to automated testing.
+    But all the requirements are important: for instance, it is imperative to
+    make sure that <command>GDB</command> works as well when cross-debugging
+    as it does in a native configuration. </para>
+
+    <para>Probably the greatest challenge was testing in a cross-development
+    environment (which can be a real nightmare).  Most cross-development
+    environments are customized by each developer.  Even when buying packaged
+    boards from vendors there are many differences.  The communication
+    interfaces vary from a serial line to ethernet.  DejaGnu was designed with
+    a modular communication setup, so that each kind of communication can be
+    added as required, and supported thereafter.  Once a communication
+    procedure is coded, any test can use it.  Currently DejaGnu can use
+    <command>rsh</command>, <command>rlogin</command>,
+    <command>telnet</command>, <command>tip</command>, 
+    <command>kermit</command>, and <command>mondfe</command> for remote 
+    communications.</para>
+
+    </sect1>
+
+    <sect1 id=posix xreflabel="A POSIX Conforming Test Framework">
+      <title>A POSIX conforming test framework</title>
+
+      <para>DejaGnu conforms to the POSIX 1003.3 standard for test
+      frameworks. I was also a member of that committe.</para>
+
+      <para>The POSIX standard 1003.3 defines what a testing framework needs to
+      provide, in order to permit the creation of POSIX conformance test
+      suites. This standard is primarily oriented to running POSIX conformance
+      tests, but its requirements also support testing of features not related
+      to POSIX conformance.  POSIX 1003.3 does not specify a particular testing
+      framework, but at this time there is only one other POSIX conforming test
+      framework: TET. TET was created by Unisoft for a consortium comprised of
+      X/Open, Unix International, and the Open Software Foundation.</para>
+
+      <para>The POSIX documentation refers to <firstterm>assertions</firstterm>.
+      An assertion is a description of behavior.  For example, if a standard
+      says ``The sun shall shine'', a corresponding assertion might be ``The
+      sun is shining.''  A test based on this assertion would pass or fail
+      depending on whether it is daytime or nighttime.  It is important to note
+      that the standard being tested is never 1003.3; the standard being tested
+      is some other standard, for which the assertions were written.</para>
+
+      <para>As there is no test suite to test testing frameworks for POSIX
+      1003.3 conformance, verifying conformance to this standard is done by
+      repeatedly reading the standard and experimenting.  One of the main
+      things 1003.3 does specify is the set of allowed output messages, and
+      their definitions.  Four messages are supported for a required feature of
+      POSIX conforming systems, and a fifth for a conditional feature. DejaGnu
+      supports the use of all five output messages; in this sense a test suite
+      that uses exactly these messages can be considered POSIX conforming.
+      These definitions specify the output of a test case:</para>
+
+      <variablelist> 
+	<varlistentry>
+	  <term>PASS</term>
+	  <listitem><para>A test has succeeded.  That is, it demonstrated that
+	  the assertion is true.</para></listitem>
+	</varlistentry>
+ 
+        <varlistentry>
+	  <term>XFAIL</term>
+	  <listitem><para>POSIX 1003.3 does not incorporate the notion of
+	  expected failures, so <emphasis>PASS</emphasis>, instead of
+	  <emphasis>XPASS</emphasis>, must also be returned for test cases
+	  which were expected to fail and did not.  This means that
+	  <emphasis>PASS</emphasis> is in some sense more ambiguous than if
+	  <emphasis>XPASS</emphasis> is also used.</para></listitem>
+	</varlistentry>
+ 
+        <varlistentry>
+	  <term>FAIL</term>
+	  <listitem><para>A test has produced the bug it was intended to
+	  capture.  That is, it has demonstrated that the assertion is false.
+	  The <emphasis>FAIL</emphasis> message is based on the test case only.
+	  Other messages are used to indicate a failure of the framework. As
+	  with <emphasis>PASS</emphasis>, POSIX tests must return
+	  <emphasis>FAIL</emphasis> rather than <emphasis>XFAIL</emphasis> even
+	  if a failure was expected.</para></listitem>
+	</varlistentry>
+ 
+        <varlistentry>
+	  <term>UNRESOLVED</term>
+	  <listitem><para>A test produced indeterminate results.  Usually, this
+	  means the test executed in an unexpected fashion; this outcome
+	  requires that a human being go over results, to determine if the test
+	  should have passed or failed.  This message is also used for any test
+	  that requires human intervention because it is beyond the abilities
+	  of the testing framework.  Any unresolved test should resolved to
+	  <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> before a test
+	  run can be considered finished.</para>
+
+	  <para>Note that for POSIX, each assertion must produce a test result
+	  code.  If the test isn't actually run, it must produce
+	  <emphasis>UNRESOLVED</emphasis> rather than just leaving that test
+	  out of the output.  This means that you have to be careful when
+	  writing tests, to not carelessly use tcl statements like
+	  <emphasis>return</emphasis>---if you alter the flow of control of the
+	  tcl code you must insure that every test still produces some result
+	  code.</para>
+
+	  <para>Here are some of the ways a test may wind up
+	  <emphasis>UNRESOLVED</emphasis>:</para>
+
+          <itemizedlist mark=bullet>
+	    <listitem><para>A test's execution is interrupted.</listitem>
+
+	    <listitem><para>A test does not produce a clear result. This is
+	    usually because there was an <emphasis>ERROR</emphasis> from
+	    DejaGnu while processing the test, or because there were three or
+	    more <emphasis>WARNING</emphasis> messages. Any 
+	    <emphasis>WARNING</emphasis> or <emphasis>ERROR</emphasis> messages
+	    can invalidate the output of the test.  This usually requires a
+	    human being to examine the output to determine what really
+	    happened---and to improve the test case.</para></listitem>
+
+	    <listitem><para>A test depends on a previous test, which
+	    fails.</para></listitem>
+
+	    <listitem><para>The test was set up incorrectly.</para></listitem>
+	  </itemizedlist>
+
+	  <varlistentry>	  
+	    <term>UNTESTED</term>
+	    <listitem><para>A test was not run.  This is a placeholder, used
+	    when there is no real test case yet.</para>
+	  </varlistentry>
+	</variablelist>
+
+	  <para>The only remaining output message left is intended to test
+	  features that are specified by the applicable POSIX standard as
+	  conditional:</para>
+
+	<variablelist>
+	  <varlistentry>	  
+  	    <term>UNSUPPORTED</term>
+	    <listitem><para>There is no support for the tested case.  This may
+  	    mean that a conditional feature of an operating system, or of a
+  	    compiler, is not implemented.  DejaGnu also uses this message when
+  	    a testing environment (often a ``bare board'' target) lacks basic
+  	    support for compiling or running the test case.  For example, a
+  	    test for the system subroutine <emphasis>gethostname</emphasis>
+  	    would never work on a target board running only a boot monitor.
+	  </varlistentry>	  
+	</variablelist>
+  
+        <para>DejaGnu uses the same output procedures to produce these messages
+	for all test suites, and these procedures are already known to conform
+	to POSIX 1003.3.  For a DejaGnu test suite to conform to POSIX 1003.3,
+	you must avoid the <emphasis>setup</emphasis>xfail} procedure as
+	described in the <emphasis>PASS</emphasis> section above, and you must
+	be careful to return <emphasis>UNRESOLVED</emphasis> where appropriate,
+	as described in the <emphasis>UNRESOLVED</emphasis> section
+	above.</para> 
+     </sect1>
+
+  </chapter>
+  
+  <!-- include the user manual -->
+  &user;
+
+  <!-- include the reference manual -->
+  &ref;
+
+</book>
diff --git a/doc/ref.sgml b/doc/ref.sgml
new file mode 100644
index 0000000..6a1a7d6
--- /dev/null
+++ b/doc/ref.sgml
@@ -0,0 +1,4242 @@
+<chapter id=reference>
+  <title>Reference</title>
+
+  <sect1 id=installation xreflabel="Installation">
+    <title>Installation</title>
+    
+    <para>Once you have the DejaGnu source unpacked and available, you must
+    first configure the software to specify where it is to run (and the
+    associated defaults); then you can proceed to installing it.</para>
+
+    <sect2 id=configuring xreflabel="Configuring DejaGnu">
+      <title>Configuring DejaGnu</title>
+
+      <para>It is usually best to configure in a directory separate from the
+      source tree, specifying where to find the source with the optional
+      <emphasis>--srcdir</emphasis> option to
+      <emphasis>configure</emphasis>. DejaGnu uses the GNU
+      <emphasis>autoconf</emphasis> to configure itself. For more info on using
+      autoconf, read the GNU autoconf manual. To configure, execute the
+      <filename>configure</filename> program, no other options are
+      required. For an example, to configure in a seperate tree for objects,
+      execute the configure script from the source tree like this:</para>
+
+      <screen>
+        ../dejagnu-1.4/configure
+      </screen>
+
+      <para>DejaGnu doesn't care at config time if it's for testing a native
+      system or a cross system. That is determined at runtime by using the
+      config files.</para>
+
+      <para>You may also want to use the <command>configure</command> option
+      <emphasis>--prefix</emphasis> to specify where you want DejaGnu and its
+      supporting code installed.  By default, installation is in subdirectories
+      of <filename>/usr/local</filename>, but you can select any alternate
+      directory <symbol>altdir</symbol> by including
+      <option>--prefix</option>{altdir}} on the
+      <command>configure</command> command line. (This value is captured in
+      the Makefile variables <emphasis>prefix</emphasis> and
+      <emphasis>exec</emphasis>prefix}.)</para>
+
+      <para>Save for a small number of example tests, the DejaGnu distribution
+      itself does not include any test suites; these are available
+      separately. Test suites for the GNU development tools are included in
+      those releases. After configuring the top-level DejaGnu directory, unpack
+      and configure the test directories for the tools you want to test; then,
+      in each test directory, run <emphasis>make check</emphasis> to build
+      auxiliary programs required by some of the tests, and run the test
+      suites.</para>
+
+    </sect2>
+    
+    <sect2 id=installing  xreflabel="Installing DejaGnu">
+      <title>Installing DejaGnu</title>
+
+      <para>To install DejaGnu in your filesystem (either in
+      <filename>/usr/local</filename>, or as specified by your
+      <emphasis>--prefix</emphasis> option to <emphasis>configure</emphasis>),
+      execute.</para>
+
+      <screen>
+        eg$ make install
+      </screen>
+
+      <para><emphasis>make install</emphasis>does thes things for
+      DejaGnu:</para>
+
+      <itemizedlist mark=bullet>
+        <listitem><para>Look in the path specified for executables
+          <symbol>$exec_prefix</symbol>) for directories called
+          <filename>lib</filename> and <filename>bin</filename>. If these
+          directories do not exist, <emphasis>make install</emphasis> creates
+          them.</para></listitem>
+
+        <listitem><para>Create another directory in the
+        <filename>share</filename> directory, called
+        <filename>dejagnu</filename>, and copy all the library files into
+        it.</listitem>
+
+        <listitem><para>Create a directory in the
+        <filename>dejagnu/share</filename> directory, called
+        <filename>config</filename>, and copy all the configuration files into
+        it.</listitem>
+
+	<listitem><para>Copy the <emphasis>runtest</emphasis> shell script into
+	<filename>$exec_prefix/bin</filename>.
+
+	<listitem><para>Copy <filename>runtest.exp</filename> into
+	<filename>$exec_prefix/lib/dejagnu</filename>. This is the main Tcl
+	code implementing DejaGnu.</para></listitem>
+
+      </itemizedlist>
+  </sect2>
+  </sect1>
+
+  <sect1 id=builtins xreflabel="Builtin Procedures">
+    <title>Builtin Procedures</title>
+
+    <para>DejaGnu provides these Tcl procedures.</para>
+
+    <sect2 id=coreprocs xreflabel="Core Internal Procedures">
+      <title>Core Internal Procedures</title>
+
+      <sect3 id=mailfile xreflabel="mail_file procedure">
+        <title>Mail_file Procedure</title>
+
+	<funcsynopsis role="tcl">
+            <funcdef><function>mail_file</function></funcdef>
+	    <paramdef><parameter>file to subject</parameter</paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+      <sect3 id=openlogs xreflabel="open_logs procedure">
+        <title>Open_logs Procedure</title>
+
+	<para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>open_logs</function></funcdef>
+	    <paramdef><parameter></parameter</paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=closelogs xreflabel="close_logs procedure">
+	  <title>Close_logs Procedure</title>
+
+	  <para></para>	
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>close_logs</function></funcdef>
+	    <paramdef><parameter></parameter</paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=isbuild xreflabel="isbuild procedure">
+	  <title>Isbuild Procedure</title>
+
+	  <para>Tests for a particular build host environment.  If the
+	  currently configured host matches the argument string, the result is
+	  <emphasis>1</emphasis>; otherwise the result is
+	  <emphasis>0</emphasis>.  <emphasis>host</emphasis> must be a full
+	  three-part configure host name; in particular, you may not use the
+	  shorter nicknames supported by configure (but you can use wildcard
+	  characters, using shell syntax, to specify sets of names). If it is
+	  passed a NULL string, then it returns the name of the build canonical
+	  configuration.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>isbuild</function></funcdef>
+	    <paramdef><parameter>pattern</parameter</paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>pattern</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=isremote xreflabel="is_remote procedure">
+	  <title>Is_remote Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>is_remote</function></funcdef>
+	    <paramdef><parameter>board</parameter</paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=is3way xreflabel="is3way procedure">
+	  <title>is3way Procedure</title>
+
+	  <para>Tests for a canadian cross. This is when the tests will be run
+	  on a remotly hosted cross compiler. If it is a canadian cross, then
+	  the result is <emphasis>1</emphasis>; otherwise the result is
+	  <emphasis>0</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>is3way</function></funcdef>
+	    <paramdef><parameter></parameter</paramdef>
+        </funcsynopsis>
+	</sect3>	
+
+	<sect3 id=ishost xreflabel="ishost procedure">
+	  <title>Ishost Procedure</title>
+
+	  <para>Tests for a particular host environment.  If the currently
+	  configured host matches the argument string, the result is
+	  <emphasis>1</emphasis>; otherwise the result is
+	  <emphasis>0</emphasis>. <emphasis>host</emphasis> must be a full
+	  three-part configure host name; in particular, you may not use the
+	  shorter nicknames supported by configure (but you can use wildcard
+	  characters, using shell syntax, to specify sets of names).</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>ishost</function></funcdef>
+	    <paramdef><parameter>pattern</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=istarget xreflabel="istarget procedure">
+	  <title>Istarget Procedure</title>
+
+ 	  <para>Tests for a particular target environment.  If the currently
+	  configured target matches the argument string, the result is
+	  <emphasis>1</emphasis> ; otherwise the result is
+	  <emphasis>0</emphasis>.  target must be a full three-part configure
+	  target name; in particular, you may not use the shorter nicknames
+	  supported by configure (but you can use wildcard characters, using
+	  shell syntax, to specify sets of names). If it is passed a
+	  <emphasis>NULL</emphasis> string, then it returns the name of the
+	  build canonical configuration.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>istarget</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=isnative xreflabel="isnative procedure">
+	  <title>Isnative Procedure</title>
+
+	  <para>Tests whether the current configuration has the same host and
+	  target. When it runs in a native configuration this procedure returns
+	  a <emphasis>1</emphasis>; otherwise it returns a
+	  <emphasis>0</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>isnative</function></funcdef>
+	    <paramdef><parameter></parameter</paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=unknown xreflabel="unknown procedure">
+	  <title>Unknown Procedure</title>
+
+	  <para></para>	
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>unknown</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=cloneoutput xreflabel="clone_output procedure">
+	  <title>Clone_output Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>clone_output</function></funcdef>
+	    <paramdef><parameter>message</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>message</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=resetvars xreflabel="reset_vars procedure">
+	  <title>Reset_vars Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>reset_vars</function></funcdef>
+	    <paramdef><parameter></parameter</paramdef>
+        </funcsynopsis>
+	</sect3>	
+
+	<sect3 id=logandexit xreflabel="log_and_exit procedure">
+	  <title>Log_and_exit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>log_and_exit</function></funcdef>
+	    <paramdef><parameter></parameter</paramdef>
+        </funcsynopsis>
+	</sect3>	
+
+	<sect3 id=logsummary xreflabel="log_summary procedure">
+	  <title>Log_summary Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+          <funcdef><function>log_summary</function></funcdef>
+	    <paramdef><parameter>args</parameter</paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>	
+
+	<sect3 id=cleanup xreflabel="cleanup procedure">
+	  <title>Cleanup Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>cleanup</function></funcdef>
+	    <paramdef><parameter></parameter</paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=setupxfail xreflabel="setup_xfail procedure">
+	  <title>Setup_xfail Procedure</title>
+
+	  <para>Declares that the test is expected to fail on a particular set
+	  of configurations.  The config argument must be a list of full
+	  three-part configure target name; in particular, you may not use the
+	  shorter nicknames supported by configure (but you can use the common
+	  shell wildcard characters to specify sets of names).  The
+	  <emphasis>bugid</emphasis> argument is optional, and used only in the
+	  logging file output; use it as a link to a bug-tracking system such
+	  as <productname>GNATS</productname>.</para>
+
+	  <para>Once you use <function>setup_xfail</function>, the
+	  <function>fail</function> and <function>pass</function> procedures
+	  produce the messages <emphasis>XFAIL</emphasis> and
+	  <emphasis>XPASS</emphasis> respectively, allowing you to distinguish
+	  expected failures (and unexpected success!) from other test
+	  outcomes.</para>
+
+	  <warning><para>Warning you must clear the expected failure after
+	  using setup_xfail in a test case.  Any call to <function>pass
+	  </function>or <function>fail</function>l clears the expected failure
+	  implicitly; if the test has some other outcome, e.g. an error, you
+	  can call <function>clear_xfail</function> to clear the expected
+	  failure explicitly.  Otherwise, the expected-failure declaration
+	  applies to whatever test runs next, leading to surprising
+	  results.</para></warning>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>setup_xfail</function></funcdef>
+	    <paramdef><parameter>config</parameter>
+	    <parameter>bugid</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>config</parameter></term>
+	    <listitem><para>The config triplet to trigger whether this is an
+	    unexpected or expect failure.</para></listitem>
+          </varlistentry>
+	  <varlistentry>
+	    <term><parameter>bugid</parameter></term>
+	    <listitem><para>The optional bugid, used to tie it this test case
+	    to a bug tracking system.</para></listitem>
+          </varlistentry>
+	</variablelist>
+      </sect3>
+
+	<sect3 id=recordtest xreflabel="record_test procedure">
+	  <title>Record_test Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>record_test</function></funcdef>
+	    <paramdef><parameter>type</parameter>
+		<parameter>message</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>type</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>message</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=pass xreflabel="pass procedure">
+          <title>Pass Procedure</title>
+
+	  <para>Declares a test to have passed. <function>pass</function>
+	  writes in the log files a message beginning with
+	  <emphasis>PASS</emphasis> (or <emphasis>XPASS</emphasis>, if failure
+	  was expected), appending the argument
+	  <parameter>string</parameter>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>pass</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this PASS
+	    message.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=fail xreflabel="fail procedure">
+          <title>Fail Procedure</title>
+
+	  <para>Declares a test to have failed.  <function>fail</function>
+	  writes in the log files a message beginning with
+	  <emphasis>FAIL</emphasis> (or <emphasis>XFAIL</emphasis>, if failure
+	  was expected), appending the argument
+	  <parameter>string</parameter>.</para> 
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>fail</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this FAIL
+	    message.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=xpass xreflabel="xpass procedure">
+          <title>Xpass Procedure</title>
+
+	  <para>Declares a test to have unexpectably passed, when it was
+	  expected to be a failure.  <function>xpass</function>
+	  writes in the log files a message beginning with
+	  <emphasis>XPASS</emphasis> (or <emphasis>XFAIL</emphasis>, if failure
+	  was expected), appending the argument
+	  <parameter>string</parameter>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>xpass</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this output
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=xfail xreflabel="xfail procedure">
+          <title>Xfail Procedure</title>
+
+	  <para>Declares a test to have expectably
+	  failed. <function>xfail</function> 
+	  writes in the log files a message beginning with
+	  <emphasis>XFAIL</emphasis> (or <emphasis>PASS</emphasis>, if success
+	  was expected), appending the argument
+	  <parameter>string</parameter>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>xpass</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this output
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=setwarningthreshold xreflabel="set_warning_threshold procedure">
+          <title>Set_warning_threshold Procedure</title>
+
+	  <para>Sets the value of <symbol>warning_threshold</symbol>. A value
+	  of <emphasis>0</emphasis> disables it: calls to
+	  <function>warning</function> will not turn a
+	  <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> into an
+	  <emphasis>UNRESOLVED</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>set_warning_threshold</function></funcdef>
+	    <paramdef><parameter>threshold</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>threshold</parameter></term>
+	    <listitem><para>This is the value of the new warning
+	    threshold.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=getwarningthreshold xreflabel="get_warning_threshold procedure">
+          <title>Get_warning_threshold Procedure</title>
+
+	  <para>Returns the current value of
+	  <symbol>{warning_threshold</symbol>. The default value is 3. This
+	  value controls how many <function>warning</function> procedures can
+	  be called before becoming <emphasis>UNRESOLVED</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>get_warning_threshold</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+
+      <sect3 id=warning xreflabel="warning procedure">
+        <title>Warning Procedure</title>
+
+	<para>Declares detection of a minor error in the test case
+	itself. <function>warning</function> writes in the log files a message
+	beginning with <emphasis>WARNING</emphasis>, appending the argument
+	<parameter>string</parameter>.  Use <function>warning</function> rather
+	than <function>perror</function> for cases (such as communication
+	failure to be followed by a retry) where the test case can recover from
+	the error. If the optional <parameter>number</parameter> is supplied,
+	then this is used to set the internal count of warnings to that
+	value.</para>
+
+	<para>As a side effect, <symbol>warning_threshold</symbol> or more
+	calls to warning in a single test case also changes the effect of the
+	next <function>pass</function> or <function>fail</function> command:
+	the test outcome becomes <emphasis>UNRESOLVED</emphasis> since an
+	automatic <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> may
+	not be trustworthy after many warnings.  If the optional numeric value
+	is <emphasis>0</emphasis>, then there are no further side effects to
+	calling this function, and the following test outcome doesn't become
+	<emphasis>UNRESOLVED</emphasis>. This can be used for errors with no
+	known side effects.</para> 
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>warning</function></funcdef>
+	    <paramdef><parameter>string</parameter>
+	    <parameter>number</parameter>
+	    </paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>number</parameter></term>
+	    <listitem><para>The optional number to set the error counter. Thius
+	    is only used to fake out the counter when using the
+	    <function>xfail</function> procedure to control when it flips the
+	    output over to <emphasis>UNRESOLVED</emphasis>
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+
+      <sect3 id=perror xreflabel="perror procedure">
+        <title>Perror Procedure</title>
+
+	<para>Declares a severe error in the testing framework
+	itself. <function>perror</function> writes in the log files a message
+	beginning with <emphasis>ERROR</emphasis>, appending the argument
+	<parameter>string</parameter>.</para>
+
+	<para>As a side effect, perror also changes the effect of the next
+	<function>pass</function> or <function>fail</function> command: the
+	test outcome becomes <emphasis>UNRESOLVED</emphasis>, since an
+	automatic <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> cannot
+	be trusted after a severe error in the test framework.  If the optional
+	numeric value is <emphasis>0</emphasis>, then there are no further side
+	effects to calling this function, and the following test outcome
+	doesn't become <emphasis>UNRESOLVED</emphasis>. This can be used for
+	errors with no known side effects.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>perror</function></funcdef>
+	    <paramdef><parameter>string</parameter>
+	    <parameter>number</parameter>
+	    </paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>number</parameter></term>
+	    <listitem><para>The optional number to set the error counter. Thius
+	    is only used to fake out the counter when using the
+	    <function>xfail</function> procedure to control when it flips the
+	    output over to <emphasis>UNRESOLVED</emphasis>
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+
+       <sect3 id=note xreflabel="note procedure">
+        <title>Note Procedure</title>
+
+	<para>Appends an informational message to the log
+	file. <function>note</function> writes in the log files a message
+	beginning with <emphasis>NOTE</emphasis>, appending the argument
+	<parameter>string</parameter>.  Use <function>note</function>
+	sparingly. The <function>verbose</function> should be used for most
+	such messages, but in cases where a message is needed in the log file
+	regardless of the verbosity level use <function>note</function>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>note</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this note.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+       <sect3 id=untested xreflabel="untested procedure">
+        <title>Untested Procedure</title>
+
+	<para>Declares a test was not run. <function>untested</function> writes
+	in the log file a message beginning with <emphasis>UNTESTED</emphasis>,
+	appending the argument <emphasis>string</emphasis>. For example, you
+	might use this in a dummy test whose only role is to record that a test
+	does not yet exist for some feature.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>untested</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this output
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+       <sect3 id=unresolved xreflabel="unresolved procedure">
+        <title>Unresolved Procedure</title>
+
+	<para>Declares a test to have an unresolved
+	outcome. <function>unresolved</function> writes in the log file a
+	message beginning with <emphasis>UNRESOLVED</emphasis>, appending the
+	argument <emphasis>string</emphasis>.  This usually means the test did
+	not execute as expected, and a human being must go over results to
+	determine if it passed or failed (and to improve the test case).</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>unresolved</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this output
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+       <sect3 id=unsupported xreflabel="unsupported procedure">
+        <title>Unsupported Procedure</title>
+
+	<para>Declares that a test case depends on some facility that does not
+	exist in the testing environment. <function>unsupported</function>
+	writes in the log file a message beginning with
+	<emphasis>UNSUPPORTED</emphasis>, appending the argument string.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>unsupported</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this output
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=inittestcounts xreflabel="init_testcounts procedure">
+	  <title>Init_testcounts Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>init_testcounts</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=incrcount xreflabel="incr_count procedure">
+	  <title>Incr_count Procedure</title>
+
+	  <para></para>	
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>incr_count</function></funcdef>
+	    <paramdef><parameter>name</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=transform xreflabel="transform procedure">
+	  <title>transform Procedure</title>
+
+	  <para>Generates a string for the name of a tool as it was configured
+	  and installed, given its native name (as the argument
+	  <parameter>toolname</parameter>). This makes the assumption that all
+	  tools are installed using the same naming conventions: For example,
+	  for a cross compiler supporting the <emphasis>m68k-vxworks</emphasis>
+	  configuration, the result of transform <command>gcc</command> is
+	  <command>m68k-vxworks-gcc</command>.</para> 
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>transform</function></funcdef>
+	    <paramdef><parameter>toolname</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>toolname</parameter></term>
+	    <listitem><para>The name of the cross-development program to
+	    transform.</para></listitem> 
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+
+	<sect3 id=checkconditionalxfail xreflabel="check_conditional_xfail procedure">
+	  <title>Check_conditional_xfail Procedure</title>
+
+	  <para>This procedure adds a condition xfail, based on compiler
+	  options used to create a test case executable. If an include options
+	  is found in the compiler flags, and it's the right architecture,
+	  it'll trigger an <emphasis>XFAIL</emphasis>. Otherwise it'll produce
+	  an ordinary <emphasis>FAIL</emphasis>. You can also specify flags to
+	  exclude. This makes a result be a <emphasis>FAIL</emphasis>, even if
+	  the included options are found. To set the conditional, set
+	  the variable <symbol>compiler_conditional_xfail_data</symbol> to the
+	  fields <programlisting>"[message string] [targets list] [includes
+	  list] [excludes list]"</programlisting> (descriptions below). This is
+	  the checked at pass/fail decision time, so there is no need to call
+	  the procedure yourself, unless you wish to know if it gets
+	  triggered. After a pass/fail, the variable is reset, so it doesn't
+	  effect other tests. It returns <emphasis>1</emphasis> if the
+	  conditional is true, or <emphasis>0</emphasis> if the conditional is
+	  false.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>check_conditional_xfail</function></funcdef>
+	    <paramdef><parameter>message</parameter>
+	    <parameter>targets</parameter>
+	    <parameter>includes</parameter>
+	    <parameter>excludes</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>message</parameter></term>
+	    <listitem><para>This is the message to print with the normal test
+	    result.</para></listitem>
+          </varlistentry>
+         <varlistentry>
+	    <term><parameter>targets</parameter></term>
+	    <listitem><para>This is a string with the list targets to activate
+	    this conditional on.</para></listitem>
+          </varlistentry>
+         <varlistentry>
+	    <term><parameter>includes</parameter></term>
+	    <listitem><para>This is a list of sets of options to search for in
+	    the compiler options to activate this conditional. If any set of
+	    the options matches, then this conditional is
+	    true.</para></listitem>
+          </varlistentry>
+         <varlistentry>
+	    <term><parameter>excludes</parameter></term>
+	    <listitem><para>This is a list of sets of options to search for in
+	    the compiler options to activate this conditional. If any set of
+	    the options matches, (regardless of whether any of the include sets
+	    match) then this conditional is de-activated.</para></listitem> 
+          </varlistentry>
+	</variablelist>
+
+	<example>
+	  <title>Specifying the conditional xfail data</title>
+
+	  <programlisting>
+	  set compiler_conditional_xfail_data { \
+	       "I sure wish I knew why this was hosed" \
+               "sparc*-sun*-* *-pc-*-*" \
+               {"-Wall -v" "-O3"} \
+               {"-O1" "-Map"} \
+          }
+	  </programlisting>
+
+	  </example>
+
+	  <para>What this does is it matches only for these two targets if
+	  "-Wall -v" or  "-O3" is set, but neither "-O1" or "-Map" is set. For
+	  a set to match, the options specified are searched for independantly
+	  of each other, so a "-Wall -v" matches either "-Wall -v" or "-v
+	  -Wall". A space seperates the options in the string. Glob-style
+	  regular expressions are also permitted.</para>
+
+	</sect3>
+
+	<sect3 id=clearxfail xreflabel="clear_xfail procedure">
+	  <title>Clear_xfail Procedure</title>
+
+	  <para>Cancel an expected failure (previously declared with
+	  <command>setup_xfail</command>) for a particular set of
+	  configurations.  The <parameter>config</parameter> argument is a list
+	  of configuration target names.  It is only necessary to call
+	  <command>clear_xfail</command> if a test case ends without calling
+	  either <command>pass</command> or <command>fail</command>, after
+	  calling <command>setup_xfail</command>.</para> 
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>clear_xfail</function></funcdef>
+	    <paramdef><parameter>config</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>config</parameter></term>
+ 	    <listitem><para>The configuration triplets to
+ 	    clear.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=verbose xreflabel="verbose procedure">
+	  <title>Verbose Procedure</title>
+
+	  <para>Test cases can use this function to issue helpful messages
+	  depending on the number of <option>--verbose</option> options on the
+	  runtest command line.  It prints string if the value of the variable
+	  <symbol>verbose</symbol> is higher than or equal to the optional
+	  number. The default value for number is <emphasis>1</emphasis>.  Use
+	  the optional <option>-log</option> argument to cause string to always
+	  be added to the log file, even if it won't be printed.  Use the
+	  optional <option>-n</option> argument to print string without a
+	  trailing newline.  Use the optional <option>--</option> argument if
+	  string begins with "-".</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>verbose</function></funcdef>
+	    <paramdef><parameter>-log</parameter>
+	    <parameter>-n</parameter>
+	    <parameter>-r</parameter>
+	    <parameter>string</parameter>
+	    <parameter>number</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>-log</parameter></term>
+ 	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>-n</parameter></term>
+ 	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>--</parameter></term>
+ 	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+ 	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>number</parameter></term>
+ 	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=loadlib xreflabel="load_lib procedure">
+	  <title>Load_lib Procedure</title>
+
+	  <para>Loads a DejaGnu library file by searching a fixed path built
+	  into DejaGnu. If DejaGnu has been installed, it looks in a path
+	  starting with the installed library directory.  If you are running
+	  DejaGnu directly from a source directory, without first running
+	  <command>make install</command>, this path defaults to the current
+	  directory.  In either case, it then looks in the current directory
+	  for a directory called <filename>lib</filename>.  If there are
+	  duplicate definitions, the last one loaded takes precedence over the
+	  earlier ones.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>load_lib</function></funcdef>
+	    <paramdef><parameter>filespec</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>filespec</parameter></term>
+ 	    <listitem><para>The name of the DejaGnu library file to
+	    load.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+    </sect2>
+
+    <sect2 id=remoteprocs>
+      <title>Procedures For Remote Communication</title>
+
+      <para><filename>lib/remote.exp</filename> defines these
+	functions, for establishing and managing communications. Each
+	of these procedures tries to establish the connection up to
+	three times before returning. Warnings (if retries will
+	continue) or errors (if the attempt is abandoned) report on
+	communication failures.  The result for any of these
+	procedures is either <emphasis>-1</emphasis>, when the
+	connection cannot be established, or the spawn ID returned by
+	the <productname>Expect</productname> command
+	<command>spawn</command>.</para>
+	
+	<para>It use the value of the <symbol>connect</symbol> field
+	in the <symbol>target_info</symbol> array (was
+	<symbol>connectmode</symbol> as the type of connection to
+	make. Current supported connection types are tip, kermit,
+	telnet, rsh, rlogin, and netdata. If the <option>--reboot</option>
+	option was used on the runtest command line, then the target
+	is rebooted before the connection is made.</para>
+
+	<sect3 id=callremote xreflabel="call_remote procedure">
+	  <title>Call_remote Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>call_remote</function></funcdef>
+	    <paramdef><parameter>type</parameter>
+		<parameter>proc</parameter>
+		<parameter>dest</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+           <varlistentry>
+	     <term><parameter>proc</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+           <varlistentry>
+	     <term><parameter>dest</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+           <varlistentry>
+	     <term><parameter>args</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=checkforboardstatus xreflabel="check_for_board_status
+	 procedure">
+	   <title>Check_for_board_status Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>check_for_board_status</function></funcdef>
+	    <paramdef><parameter>variable</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+             <varlistentry>
+	       <term><parameter>variable</parameter></term>
+	        <listitem><para></para></listitem>
+         </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=fileonbuild xreflabel="file_on_build procedure">
+	   <title>File_on_build Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>file_on_build</function></funcdef>
+	    <paramdef><parameter>op</parameter>
+		<parameter>file</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+           <varlistentry>
+	     <term><parameter>op</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+           <varlistentry>
+	     <term><parameter>file</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+           <varlistentry>
+	     <term><parameter>args</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=fileonhost xreflabel="file_on_host procedure">
+	   <title>File_on_host Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>file_on_host</function></funcdef>
+	    <paramdef><parameter>op</parameter>
+		<parameter>file</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+           <varlistentry>
+	     <term><parameter>op</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+           <varlistentry>
+	     <term><parameter>file</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+           <varlistentry>
+	     <term><parameter>args</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=localexec xreflabel="local_exec procedure">
+	   <title>Local_exec Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>local_exec</function></funcdef>
+	    <paramdef><parameter>commandline</parameter>
+		<parameter>inp</parameter>
+		<parameter>outp</parameter>
+		<parameter>timeout</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+           <varlistentry>
+	       <term><parameter>inp</parameter></term>
+	        <listitem><para></para></listitem>
+           </varlistentry>
+           <varlistentry>
+	       <term><parameter>outp</parameter></term>
+	        <listitem><para></para></listitem>
+           </varlistentry>
+           <varlistentry>
+	       <term><parameter>timeout</parameter></term>
+	        <listitem><para></para></listitem>
+           </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=remotebinary xreflabel="remote_binary procedure">
+	   <title>Remote_binary Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_binary</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	     <term><parameter>host</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=remoteclose xreflabel="remote_close procedure">
+	   <title>Remote_close Procedure</title>
+
+	   <para></para>	
+
+	  <funcsynopsis role="tcl"> 
+            <funcdef><function>remote_close</function></funcdef>
+	    <paramdef><parameter>shellid</parameter></paramdef>
+          </funcsynopsis>
+	  <variablelist>
+             <varlistentry>
+	       <term><parameter>shellid</parameter></term>
+	        <listitem><para>This is the value returned by a call
+	        to <function>remote_open</function>. This closes the
+	        connection to the target so resources can be used by
+	        others. This parameter can be left off if the
+	        <symbol>fileid</symbol> field in the
+	        <symbol>target_info</symbol> array is set.</para></listitem>
+           </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=remotedownload xreflabel="remote_download procedure">
+	   <title>Remote_download Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl"> 
+          <funcdef><function>remote_download</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoteexec xreflabel="remote_exec procedure">
+	  <title>Remote_exec Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_exec</function></funcdef>
+	    <paramdef><parameter>hostname</parameter>
+		<parameter>program</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>hostname</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>program</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoteexpect xreflabel="remote_expect procedure">
+	  <title>Remote_expect Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_expect</function></funcdef>
+	    <paramdef><parameter>board</parameter>
+		<parameter>timeout</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>board</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>timeout</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remotefile xreflabel="remote_file procedure">
+	  <title>Remote_file Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_file</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>args</parameter</paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoteld xreflabel="remote_ld procedure">
+	  <title>Remote_ld Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_ld</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>prog</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>prog</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoteload xreflabel="remote_load procedure">
+	  <title>Remote_load Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_load</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>prog</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>prog</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoteopen xreflabel="remote_open procedure">
+	  <title>Remote_open Procedure</title>
+
+	  <para></para>
+
+	  <funcsynopsis role="tcl"> 
+            <funcdef><function>remote_open</function></funcdef>
+	      <paramdef><parameter>type</parameter></paramdef>
+            </funcsynopsis>
+            <variablelist>
+              <varlistentry>
+		<term><parameter>type</parameter></term>
+	        <listitem><para>This is passed <option>host</option> or
+                <option>target</option>. Host or target refers to
+	      whether it is a connection to a remote target, or a
+	      remote host. This opens the connection to the desired
+	      target or host using the default values in the
+	      configuration system. It returns that
+	      <symbol>spawn_id</symbol> of the process that manages
+	      the connection. This value can be used in
+	      <productname>Expect</productname> or
+	      <command>exp_send</command> statements, or passed to
+	      other procedures that need the connection process's
+	      id. This also sets the <symbol>fileid</symbol> field in
+	      the <symbol>target_info</symbol> array.</para></listitem>
+         </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=remotepopconn xreflabel="remote_pop_conn procedure">
+	   <title>Remote_pop_conn Procedure</title>
+
+	   <para></para>	
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_pop_conn</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remotepushconn xreflabel="remote_push_conn procedure">
+	  <title>Remote_push_conn Procedure</title>
+
+	  <para></para>	
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_push_conn</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoterawbinary xreflabel="remote_raw_binary procedure">
+	  <title>Remote_raw_binary Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_raw_binary</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoterawclose xreflabel="remote_raw_close procedure">
+	  <title>Remote_raw_close Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_raw_close</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoterawfile xreflabel="remote_raw_file procedure">
+	  <title>Remote_raw_file Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_raw_file</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoterawld xreflabel="remote_raw_ld procedure">
+	  <title>remote_raw_ld Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_raw_ld</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>prog</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>prog</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoterawload xreflabel="remote_raw_load procedure">
+	  <title>Remote_raw_load Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_raw_load</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>prog</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>prog</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoterawopen xreflabel="remote_raw_open procedure">
+	  <title>Remote_raw_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_raw_open</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoterawsend xreflabel="remote_raw_send procedure">
+	  <title>Remote_raw_send Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_raw_send</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoterawspawn xreflabel="remote_raw_spawn procedure">
+	  <title>Remote_raw_spawn Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_raw_spawn</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>commandline</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>commandline</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoterawtransmit xreflabel="remote_raw_transmit
+	procedure">
+	  <title>Remote_raw_transmit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_raw_transmit</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoterawwait xreflabel="remote_raw_wait procedure">
+	  <title>Remote_raw_wait Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_raw_wait</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>timeout</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>timeout</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remotereboot xreflabel="remote_reboot procedure">
+	  <title>Remote_reboot Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_reboot</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remotesend xreflabel="remote_send procedure">
+	  <title>Remote_send Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_send</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remotespawn xreflabel="remote_spawn procedure">
+	  <title>Remote_spawn Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_spawn</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>commandline</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>commandline</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoteswapconn xreflabel="remote_swap_conn procedure">
+	  <title>Remote_swap_conn Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_swap_conn</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remotetransmit xreflabel="remote_transmit procedure">
+	  <title>Remote_transmit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_transmit</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remoteupload xreflabel="remote_upload procedure">
+	  <title>Remote_upload Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_upload</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>srcfile</parameter>
+		<parameter>arg</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>srcfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>arg</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=remotewait xreflabel="remote_wait procedure">
+	  <title>Remote_wait Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>remote_wait</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>timeout</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>timeout</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standardclose xreflabel="standard_close procedure">
+	  <title>Standard_close Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_close</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standarddownload xreflabel="standard_download procedure">
+	  <title>Standard_download Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_download</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter>
+		<parameter>destfile</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>destfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standardexec xreflabel="standard_exec procedure">
+	  <title>Standard_exec Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_exec</function></funcdef>
+	    <paramdef><parameter>hostname</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>hostname</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standardfile xreflabel="standard_file procedure">
+	  <title>Standard_file Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_file</function></funcdef>
+	    <paramdef><parameter>dest</parameter
+		<parameter>op</parameter
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standardload xreflabel="standard_load procedure">
+	  <title>Standard_load Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_load</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>prog</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>prog</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standardreboot xreflabel="standard_reboot procedure">
+	  <title>Standard_reboot Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_reboot</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standardsend xreflabel="standard_send procedure">
+	  <title>Standard_send Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_send</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>string</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standardspawn xreflabel="standard_spawn procedure">
+	  <title>Standard_spawn Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_spawn</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>commandline</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>commndline</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standardtransmit xreflabel="standard_transmit procedure">
+	  <title>Standard_transmit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_transmit</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standardupload xreflabel="standard_upload procedure">
+	  <title>Standard_upload Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_upload</function></funcdef>
+	    <paramdef><parameter>dest srcfile destfile</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>srcfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>destfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=standardwait xreflabel="standard_wait procedure">
+	  <title>Standard_wait Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>standard_wait</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>timeout</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>timeout</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=unixcleanfilename xreflabel="unix_clean_filename
+	procedure">
+	  <title>Unix_clean_filename Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>unix_clean_filename</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+<!-- FIXME: this doesn't seem to exist anymore
+	<sect3 id=exitremoteshell xreflabel="exit_remote_shell procedure">
+	  <title>exit_remote_shell Procedure</title>
+
+	  <para></para>
+
+          <funcsynopsis role="tcl"> 
+            <funcdef><function>exit_remote_shell</function></funcdef>
+              <paramdef><parameter>spawnid</parameter></paramdef>
+            </funcsynopsis>
+            <variablelist>
+              <varlistentry>
+                <term><parameter>spawnid</parameter></term>
+                <listitem><para>Exits a remote process started by any
+                of the connection procedures. <symbol>spawnid</symbol>
+                is the result of the connection procedure that started
+                the remote process.</para></listitem>
+           </varlistentry>
+         </variablelist>
+	 </sect3>
+-->
+
+    </sect2>
+ 
+    <sect2 id=connprocs xreflabel="connprocs">
+      <title>Procedures For Using Utilities to Connect</title>
+
+      <para>telnet, rsh, tip, kermit</para>
+
+      <sect3 id=telnet xreflabel="telnet procedure">
+        <title>telnet Procedure</title>
+
+	<para></para>
+
+	  <funcsynopsis role="tcl">
+	    <funcdef><function>telnet</function></funcdef>
+	    <paramdef><parameter>hostname</parameter>
+	    <parameter>port</parameter></paramdef>
+          </funcsynopsis>
+          <funcsynopsis role="tcl">
+	    <funcdef><function>rlogin</function></funcdef>
+	    <paramdef><parameter>hostname</parameter></paramdef>
+          </funcsynopsis>
+	  </sect3>
+
+	  <sect3 id=rsh xreflabel="rsh procedure">
+	    <title>rsh Procedure</title>
+
+	    <para></para>
+
+          <funcsynopsis role="tcl">
+	    <funcdef><function>rsh</function></funcdef>
+	    <paramdef><parameter>hostname</parameter></paramdef>
+          </funcsynopsis>
+	  <variablelist>
+             <varlistentry>
+	       <term><parameter>hostname</parameter></term>
+	       <listitem><para>This refers to the IP address or name
+	        (for example, an entry in
+	        <filename>/etc/hosts</filename>) for this target. The
+	        procedure names reflect the Unix utility used to
+	        establish a connection. The optional
+	        <parameter>port</parameter> is used to specify the IP
+	        port number. The value of the
+	        <parameter>netport</parameter> field in the
+	        <symbol>target_info</symbol> array is used. (was
+	        <symbol>$netport</symbol>) This value has two parts,
+	        the hostname and the port number, seperated by a
+	        <emphasis>:</emphasis>. If host or target is used in
+	        the <symbol>hostname</symbol> field, than the
+	        config array is used for all information.</para></listitem>
+         </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=tip xreflabel="tip procedure">
+	   <title>Tip Procedure</title>
+
+	   <para></para>
+
+	 <funcsynopsis role="tcl">
+           <funcdef><function>tip</function></funcdef>
+            <paramdef><parameter>port</parameter></paramdef>
+          </funcsynopsis>
+          <variablelist>
+             <varlistentry>
+               <term><parameter>port</parameter></term>
+               <listitem><para>Connect using the Unix utility
+               <command>tip</command>. <parameter>Port</parameter>must
+               be a name from the <productname>tip</productname>
+               configuration file
+               <filename>/etc/remote</filename>. Often, this is called
+               <symbol>hardwire</symbol>, or something like
+               <symbol>ttya</symbol>. This file holds all the
+               configuration data for the serial port. The value of
+               the <symbol>serial</symbol> field in the
+               <symbol>target_info</symbol> array is used. (was
+               <symbol>$serialport</symbol>) If <option>host</option>
+               or <option>target</option> is used in the
+               <parameter>port</parameter> field, than the config
+               array is used for all information. the
+	       config array is used for all information.</para></listitem>
+         </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=kermit xreflabel="kermit procedure">
+	   <title>Kermit Procedure</title>
+
+	   <para></para>
+
+          <funcsynopsis role="tcl">
+            <funcdef><function>kermit</function></funcdef>
+            <paramdef><parameter>port</parameter>
+	    <parameter>bps</parameter></paramdef>
+          </funcsynopsis>
+          <variablelist>
+             <varlistentry>
+               <term><parameter>port</parameter></term>
+               <listitem><para>Connect using the program
+               <command>kermit</command>. <parameter>Port</parameter>
+               is the device name,
+               e.g. <filename>/dev/ttyb</filename>.
+	       </para></listitem>
+             </varlistentry>
+             <varlistentry>
+               <term><parameter>bps</parameter></term>
+               <listitem><para><parameter>bps</parameter> is the line
+               speed to use (in its per second) for the
+               connection. The value of the <symbol>serial</symbol>
+               field in the <symbol>target_info</symbol> array is
+               used.  (was <symbol>$serialport</symbol>) If
+               <option>host</option> or <option>target</option> is
+               used in the <parameter>port</parameter> field, than the
+               config array is used for all information. the
+	       config array is used for all information.</para></listitem>
+           </varlistentry>
+         </variablelist>
+	 </sect3>
+
+	 <sect3 id=kermitopen xreflabel="kermit_open procedure">
+	   <title>kermit_open Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>kermit_open</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=kermitcommand xreflabel="kermit_command procedure">
+	  <title>Kermit_command Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>kermit_command</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=kermitsend xreflabel="kermit_send procedure">
+	  <title>Kermit_send Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>kermit_send</function></funcdef>
+	    <paramdef><parameter>dest string args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=kermittransmit xreflabel="kermit_transmit procedure">
+	  <title>Kermit_transmit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>kermit_transmit</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=telnetopen xreflabel="telnet_open procedure">
+	  <title>Telnet_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>telnet_open</function></funcdef>
+	    <paramdef><parameter>hostname</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>hostname</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=telnetbinary xreflabel="telnet_binary procedure">
+	  <title>Telnet_binary Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>telnet_binary</function></funcdef>
+	    <paramdef><parameter>hostname</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>hostname</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=telnettransmit xreflabel="telnet_transmit procedure">
+	  <title>Telnet_transmit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>telnet_transmit</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=tipopen xreflabel="tip_open procedure">
+	  <title>Tip_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>tip_open</function></funcdef>
+	    <paramdef><parameter>hostname</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>hostname</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=rloginopen xreflabel="rlogin_open procedure">
+	  <title>Rlogin_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>rlogin_open</function></funcdef>
+	    <paramdef><parameter>arg</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>arg</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=rloginspawn xreflabel="rlogin_spawn procedure">
+	  <title>Rlogin_spawn Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>rlogin_spawn</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>cmdline</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>dest</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>cmdline</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=rshopen xreflabel="rsh_open procedure">
+	  <title>Rsh_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>rsh_open</function></funcdef>
+	    <paramdef><parameter>hostname</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>hostname</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=rshdownload xreflabel="rsh_download procedure">
+	  <title>Rsh_download Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>rsh_download</function></funcdef>
+	    <paramdef><parameter>desthost</parameter>
+		<parameter>srcfile</parameter>
+		<parameter>destfile</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>desthost</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>srcfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>destfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=rshupload xreflabel="rsh_upload procedure">
+	  <title>Rsh_upload Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>rsh_upload</function></funcdef>
+	    <paramdef><parameter>desthost</parameter>
+		<parameter>srcfile</parameter>
+		<parameter>destfile</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>desthost</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>srcfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>destfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=rshexec xreflabel="rsh_exec procedure">
+	  <title>Rsh_exec Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>rsh_exec</function></funcdef>
+	    <paramdef><parameter>boardname</parameter>
+		<parameter>cmd</parameter>
+		<parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>boardname</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>cmd</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=ftpopen xreflabel="ftp_open procedure">
+	  <title>Ftp_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>ftp_open</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=ftpupload xreflabel="ftp_upload procedure">
+	  <title>Ftp_upload Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>ftp_upload</function></funcdef>
+	    <paramdef><parameter>host</parameter>
+		<parameter>remotefile</parameter>
+		<parameter>localfile</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>remotefile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>localfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=ftpdownload xreflabel="ftp_download procedure">
+	  <title>Ftp_download Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>ftp_download</function></funcdef>
+	    <paramdef><parameter>host</parameter>
+		<parameter>localfile</parameter>
+		<parameter>remotefile</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>localfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>remotefile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=ftpclose xreflabel="ftp_close procedure">
+	  <title>Ftp_close Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>ftp_close</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=tipdownload xreflabel="tip_download procedure">
+	  <title>Tip_download Procedure</title>
+
+	  <para></para>
+
+          <funcsynopsis role="tcl"> 
+            <funcdef><function>tip_download</function></funcdef>
+              <paramdef><parameter>spawnid</parameter>
+              <parameter>file</parameter></paramdef>
+            </funcsynopsis>
+            <variablelist>
+              <varlistentry>
+                <term><parameter>spawnid</parameter></term>
+                <listitem><para>Download <option>file</option> to the
+                process <symbol>spawnid</symbol> (the value returned
+                when the connection was established), using the
+                <command>~put</command> command under
+                <productname>tip</productname>.  Most often used for
+                single board computers that require downloading
+                programs in ASCII S-records.  Returns
+                <emphasis>1</emphasis> if an error occurs,
+                <emphasis>0</emphasis> otherwise.</para></listitem>
+               </varlistentry>
+              <varlistentry>
+                 <term><parameter>file</parameter></term>
+                <listitem><para>This is the filename to
+                downlaod.</para></listitem>
+           </varlistentry>
+         </variablelist>
+       </sect3>
+    </sect2>
+
+    <sect2 id=targetprocs>
+      <title>Procedures For Target Boards</title>
+
+      <para></para>
+
+      <sect3 id=defaultlink xreflabel="default_link procedure">
+        <title>Default_link Procedure</title>
+
+	<para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>default_link</function></funcdef>
+	    <paramdef><parameter>board</parameter>
+	    <parameter>objects</parameter>
+	    <parameter>destfile</parameter>
+	    <parameter>flags</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>board</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>objects</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>destfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>flags</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=defaulttargetassemble xreflabel="default_target_assemble
+	procedure">
+	  <title>Default_target_assemble Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>default_target_assemble</function></funcdef>
+	    <paramdef><parameter>source</parameter>
+	    <parameter>destfile</parameter>
+	    <parameter>flags</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>source</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>destfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>flags</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=defaulttargetcompile xreflabel="default_target_compile
+	procedure">
+	  <title>default_target_compile Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>default_target_compile</function></funcdef>
+	    <paramdef><parameter>source</parameter>
+	    <parameter>destfile</parameter>
+	    <parameter>type</parameter>
+	    <parameter>options</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>source</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>destfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>type</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>options</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=popconfig xreflabel="pop_config procedure">
+	  <title>Pop_config Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>pop_config</function></funcdef>
+	    <paramdef><parameter>type</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>type</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=prunewarnings xreflabel="prune_warnings procedure">
+	  <title>Prune_warnings Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>prune_warnings</function></funcdef>
+	    <paramdef><parameter>text</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>text</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=pushbuild xreflabel="push_build procedure">
+	  <title>Push_build Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>push_build</function></funcdef>
+	    <paramdef><parameter>name</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=pushconfig xreflabel="push_config procedure">
+	  <title>push_config Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>push_config</function></funcdef>
+	    <paramdef><parameter>type</parameter>
+	    <parameter>name</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>type</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=reboottarget xreflabel="reboot_target procedure">
+	  <title>Reboot_target Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>reboot_target</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=targetassemble xreflabel="target_assemble procedure">
+	  <title>Target_assemble Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>target_assemble</function></funcdef>
+	    <paramdef><parameter>source destfile flags</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>source</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>destfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>flags</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=targetcompile xreflabel="target_compile procedure">
+	  <title>Target_compile Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>target_compile</function></funcdef>
+	    <paramdef><parameter>source</parameter>
+	    <parameter>destfile</parameter>
+	    <parameter>type</parameter>
+	    <parameter>options</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>source</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>destfile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>type</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>options</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+	</sect2>
+
+	<sect2 id=targetdb xreflabel="target database library file ">
+	  <title>Target Database Procedures</title>
+
+	  <sect3 id=boardinfo xreflabel="board_info procedure">
+	    <title>Board_info Procedure</title>
+
+	    <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>board_info</function></funcdef>
+	    <paramdef><parameter>machine</parameter>
+	    <parameter>op</parameter>
+	    <parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>machine</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>op</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=hostinfo xreflabel="host_info procedure">
+	  <title>Host_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>host_info</function></funcdef>
+	    <paramdef><parameter>op</parameter>
+	    <parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>op</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=setboardinfo xreflabel="set_board_info procedure">
+	  <title>Set_board_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>set_board_info</function></funcdef>
+	    <paramdef><parameter>entry</parameter>
+	    <parameter>value</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>entry</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>value</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=setcurrtargetinfo xreflabel="set_currtarget_info
+	procedure">
+	  <title>Set_currtarget_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>set_currtarget_info</function></funcdef>
+	    <paramdef><parameter>entry</parameter>
+	    <parameter>value</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>entry</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>value</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=targetinfo xreflabel="target_info procedure">
+	  <title>Target_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>target_info</function></funcdef>
+	    <paramdef><parameter>op</parameter>
+	    <parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>op</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=unsetboardinfo xreflabel="unset_board_info procedure">
+	  <title>Unset_board_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>unset_board_info</function></funcdef>
+	    <paramdef><parameter>entry</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>entry</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=unsetcurrtargetinfo xreflabel="unset_currtarget_info
+	procedure">
+	  <title>Unset_currtarget_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>unset_currtarget_info</function></funcdef>
+	    <paramdef><parameter>entry</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>entry</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=pushtarget xreflabel="push_target procedure">
+	  <title>Push_target Procedure</title>
+
+	  <para>This makes the target named <emphasis>name</emphasis> be the
+	  current target connection. The value of <emphasis>name</emphasis> is
+	  an index into the <symbol>target_info</symbol> array and is set in
+	  the global config file.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>push_target</function></funcdef>
+	    <paramdef><parameter>name</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para>The name of the target to make current
+	    connection.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=poptarget xreflabel="poptarget procedure">
+	  <title>Pop_target Procedure</title>
+
+	  <para>This unsets the current target connection.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>pop_target</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=listtargets xreflabel="list_targets procedure">
+	  <title>List_targets Procedure</title>
+
+	  <para>This lists all the supported targets for this
+	  architecture.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>list_targets</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=pushhost xreflabel="push_host	procedure">
+	  <title>Push_host Procedure</title>
+
+	  <para>This makes the host named <emphasis>name</emphasis> be the
+	  current remote host connection. The value of
+	  <emphasis>name</emphasis> is an index into the
+	  <symbol>target_info</symbol> array and is set in the global config
+	  file.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>push_host</function></funcdef>
+	    <paramdef><parameter>name</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=pophost xreflabel="pop_host procedure">
+	  <title>Pop_host Procedure</title>
+
+	  <para>This unsets the current host connection.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>pop_host</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+	 </funcsynopsis>
+	</sect3>
+
+	<sect3 id=compile xreflabel="compile procedure">
+	  <title>Compile Procedure</title>
+
+	  <para>This invokes the compiler as set by CC to compile the 
+	  file <filename>file</filename>. The default options for many cross
+	  compilation targets are <emphasis>guessed</emphasis> by DejaGnu, and
+	  these options can be added to by passing in more parameters as
+	  arguments to <command>compile</command>. Optionally, this will also
+	  use the value of the <emphasis>cflags</emphasis> field in the target
+	  config array. If the host is not the same as the build machines, then
+	  then compiler is run on the remote host using
+	  <command>execute_anywhere</command>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>compile</function></funcdef>
+	    <paramdef><parameter>file</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=archive xreflabel="archive procedure">
+	  <title>Archive Procedure</title>
+
+	  <para>This produces an archive file. Any parameters passed to
+	  <command>archive</command> are used in addition to the default
+	  flags. Optionally, this will also use the value of the
+	  <emphasis>arflags</emphasis> field in the target config array. If the
+	  host is not the same as the build machines, then then archiver is run
+	  on the remote host using <command>execute_anywhere</command>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>archive</function></funcdef>
+	    <paramdef><parameter>file</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=ranlib xreflabel="ranlib procedure">
+	  <title>Ranlib Procedure</title>
+
+	  <para>This generates an index for the archive file for systems that
+	  aren't POSIX yet. Any parameters passed to <command>ranlib</command>
+	  are used in for the flags.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>ranlib</function></funcdef>
+	    <paramdef><parameter>file</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=executeanywhere xreflabel="execute_anywhere procedure">
+	  <title>Execute_anywhere Procedure</title>
+
+	  <para>This executes the <emphasis>cmdline</emphasis> on the proper
+	  host. This should be used as a replacement for the Tcl command
+	  <command>exec</command> as this version utilizes the target config
+	  info to execute this command on the build machine or a remote
+	  host. All config information for the remote host must be setup to
+	  have this command work. If this is a canadian cross, (where we test a
+	  cross compiler that runs on a different host then where DejaGnu is
+	  running) then a connection is made to the remote host and the command
+	  is executed there. It returns either REMOTERROR (for an error) or the
+	  output produced when the command was executed. This is used for
+	  running the tool to be tested, not a test case.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>execute_anywhere</function></funcdef>
+	    <paramdef><parameter>cmdline</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>cmdline</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+    <sect2 id=platformprocs xreflabel="platform dependant procedures">
+      <title>Platform Dependant Procedures</title>
+
+      <para>Each combination of target and tool requires some
+      target-dependent procedures.  The names of these procedures have
+      a common form: the tool name, followed by an underbar
+      <emphasis>_</emphasis>, and finally a suffix describing the
+      procedure's purpose.  For example, a procedure to extract the
+      version from <productname>GDB</productname> is called
+      <symbol>gdb_version</symbol>.</para>
+
+      <para><command>runtest</command> itself calls only two of these
+      procedures, <symbol>${tool}_exit</symbol> and
+      <symbol>${tool}_version</symbol>; these procedures use no
+      arguments.</para>
+
+      <para>The other two procedures, <symbol>${tool}_start</symbol>
+      and <symbol>${tool}_load</symbol>}, are only called by the test
+      suites themselves (or by testsuite-specific initialization
+      code); they may take arguments  or not, depending on the
+      conventions used within each test suite.</para>
+
+      <para>The usual convention for return codes from any of these
+      procedures (although it is not required by
+      <command>runtest</command>) is to return <emphasis>0</emphasis>
+      if the procedure succeeded, <emphasis>1</emphasis> if it failed,
+      and <emphasis>-1</emphasis> if there was a communication error.</para>
+	
+      	<sect3 id=toolstart xreflabel="${tool}_start procedure">
+	  <title>${tool}_start Procedure</title>
+
+	  <para>Starts a particular tool.  For an interactive tool,
+	  <function>${tool}_start</function> starts and initializes the
+	  tool, leaving the tool up and running for the test cases; an
+	  example is <function>gdb_start</function>, the start function
+	  for GDB. For a batch oriented tool,
+	  <function>${tool}_start</function> is optional; the recommended
+	  convention is to let <function>${tool}_start</function> run the
+	  tool, leaving the output in a variable called
+	  <function>comp_output</function>.  Test scripts can then analyze
+	  <function>$comp_output</function> to determine the test results.
+	  An example of this second kind of start function is
+	  <function>gcc_start</function>, the start function for GCC.</para>
+
+	  <para>DejaGnu itself does not call
+	  <function>${tool}_start</function>.  The initialization
+	  module <function>${tool}_init.exp</function> must call
+	  <function>${tool}_start</function> for interactive tools;
+	  for batch-oriented tools, each individual test script calls
+	  <function>${tool}_start</function> (or makes other
+	  arrangements to run the tool).</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>${tool}_start</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=toolload xreflabel="${tool}_load procedure">
+	  <title>${tool}_load Procedure</title>
+
+	  <para>Loads something into a tool. For an interactive tool,
+	  this conditions the tool for a particular test case; for
+	  example, <function>gdb_load</function> loads a new
+	  executable file into the debugger. For batch oriented tools,
+	  <function>${tool}_load</function> may do nothing---though,
+	  for example, the GCC support uses
+	  <function>gcc_load</function> to load and run a binary on
+	  the target environment.  Conventionally,
+	  <function>${tool}_load</function> leaves the output of any
+	  program it runs in a variable called
+	  <symbol>$exec_output</symbol>. Writing
+	  <function>${tool}_load</function> can be the most complex
+	  part of extending DejaGnu to a new tool or a new target, if
+	  it requires much communication coding or file
+	  downloading. Test scripts call
+	  <function>${tool}_load</function>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>${tool}_load</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=toolexit xreflabel="${tool}_exit procedure">
+	  <title>${tool}_exit Procedure</title>
+
+	  <para>Cleans up (if necessary) before DejaGnu exits. For
+	  interactive tools, this usually ends the interactive
+	  session.  You can also use <function>${tool}_exit</function>
+	  to remove any temporary files left over from the
+	  tests. <command>runtest</command> calls
+	  <function>${tool}_exit</function>.<para> 
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>${tool}_exit</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=toolversion xreflabel="${tool}_version procedure">
+	  <title>${tool}_version Procedure</title>
+
+	  <para>Prints the version label and number for
+	  <symbol>${tool}</symbol>.  This is called by the DejaGnu
+	  procedure that prints the final summary report.  The output
+	  should consist of the full path name used for the tested
+	  tool, and its version number.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>${tool}_version</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+    </sect2>
+
+    <sect2 id=utilprocs>
+      <title>Utility Procedures</title>
+
+      <sect3 id=getdirs xreflabel="getdirs procedure">
+        <title>Getdirs Procedure</title>
+
+      <para>Returns a list of all the directories in the single
+	directory a single directory that match an optional
+	pattern. </para>
+	
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>getdirs</function></funcdef>
+	    <paramdef><parameter>rootdir</parameter>
+		<parameter>pattern</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>pattern</parameter></term>
+	    <listitem><para>If you do not specify
+	    <parameter>pattern</parameter>,
+	    <function>Getdirs</function> assumes a default pattern of
+	    <emphasis>*</emphasis>. You may use the common shell
+	    wildcard characters in the pattern. If no directories
+	    match the pattern, then a NULL string is
+	    returned</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+      <sect3 id=find xreflabel="find procedure">
+        <title>Find Procedure</title>
+
+	<para>Search for files whose names match <emphasis>pattern</emphasis>
+	(using shell wildcard characters for filename expansion).  Search
+	subdirectories recursively, starting at
+	<emphasis>rootdir</emphasis>. The result is the list of files whose
+	names match; if no files match, the result is empty.  Filenames in the
+	result include all intervening subdirectory names. If no files match
+	the pattern, then a NULL string is returned.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>find</function></funcdef>
+	    <paramdef><parameter>rootdir</parameter>
+	    <parameter>pattern</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>rootdir</parameter></term>
+	    <listitem><para>The top level directory to search the search
+	    from.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>pattern</parameter></term>
+	    <listitem><para>A csh "glob" style regular expression reprsenting
+	    the files to find.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+        <sect3 id=which xreflabel="which procedure">
+        <title>Which Procedure</title>
+
+	<para>Searches the execution path for an executable file
+	<emphasis>binary</emphasis>, like the the BSD <command>which</command>
+	utility.  This procedure uses the shell environment variable
+	<emphasis>PATH</emphasis>. It returns <emphasis>0</emphasis> if the
+	binary is not in the path, or if there is no <emphasis>PATH</emphasis>
+	environment variable. If <command>binary</command> is in the path, it
+	returns the full path to <command>binary</command>.</para> 
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>which</function></funcdef>
+	    <paramdef><parameter>file</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>binary</parameter></term>
+	    <listitem><para>The executable program or shell script to look
+	    for.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+        <sect3 id=grep xreflabel="grep procedure">
+        <title>Grep Procedure</title>
+
+	<para>Search the file called <filename>filename</filename> (a fully
+	specified path) for lines that contain a match for regular expression
+	<emphasis>regexp</emphasis>. The result is a list of all the lines that
+	match.  If no lines match, the result is an empty string.  Specify
+	<emphasis>regexp</emphasis> using the standard regular expression style
+	used by the Unix utility program grep.</para> 
+
+	<para>Use the optional third argument <emphasis>line</emphasis> to
+	start lines in the result with the line number in
+	<filename>filename</filename>.  (This argument is simply an option
+	flag; type it just as shown <option>--line</option>.)
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>grep</function></funcdef>
+	    <paramdef><parameter>filename</parameter>
+	    <parameter>regexp</parameter>
+	    <parameter>--line</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>filename</parameter></term>
+	    <listitem><para>The file to search.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>regexp</parameter></term>
+	    <listitem><para>The Unix style regular expression (as used by the
+	    <command>grep</command> Unix utility) to search
+	    for.</para></listitem> 
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>--line</parameter></term>
+	    <listitem><para>Prefix the line number to each line where the
+	    regexp matches.</para></listitem> 
+          </varlistentry>
+	</variablelist>
+
+	</sect3>
+	<sect3 id=prune xreflabel="prune procedure">
+	  <title>Prune Procedure</title>
+
+	  <para>Remove elements of the Tcl list <emphasis>list</emphasis>.
+	  Elements are fields delimited by spaces.  The result is a copy of
+	  list, without any elements that match <emphasis>pattern</emphasis>.
+	  You can use the common shell wildcard characters to specify the
+	  pattern.</para> 
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>prune</function></funcdef>
+	    <paramdef><parameter>list</parameter>
+  	    <parameter>pattern</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>list</parameter></term>
+	    <listitem><para>A Tcl list containing the original data. Commonly
+	    this is the output of a batch executed command, like running a
+	    compiler.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>pattern</parameter></term>
+	    <listitem><para>The csh shell "glob" style pattern to search
+	    for.</para></listitem>
+          </varlistentry>
+	</variablelist>
+
+	</sect3>
+
+	<sect3 id=slay xreflabel="slay procedure">
+	  <title>Slay Procedure</title>
+
+	  <para>This look in the process table for <emphasis>name</emphasis>
+	  and send it a unix SIGINT, killing the process. This will only work
+	  under NT if you have Cygwin or another Unix system for NT
+	  installed.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>slay</function></funcdef>
+	    <paramdef><parameter>name</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para>The name of the program to kill.</para></listitem>
+          </varlistentry>
+	</variablelist>
+
+	</sect3>
+
+	<sect3 id=absolute xreflabel="absolute procedure">
+	  <title>Absolute Procedure</title>
+
+	  <para>This procedure takes the relative <emphasis>path</emphasis>,
+	  and converts it to an absolute path.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>absolute</function></funcdef>
+	    <paramdef><parameter>path</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>path</parameter></term>
+	    <listitem><para>The path to convert.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=psource xreflabel="psource procedure">
+	  <title>Psource Procedure</title>
+
+	  <para>This sources the file <emphasis>filename</emphasis>, and traps
+	  all errors. It also ignores all extraneous output. If there was an
+	  error it returns a <emphasis>1</emphasis>, otherwise it returns a
+	  <emphasis>0</emphasis>.
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>psource</function></funcdef>
+	    <paramdef><parameter>file</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>filename</parameter></term>
+	    <listitem><para>The filename to Tcl script to
+	    source.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=runtestfilep xreflabel="runtest_file_p procedure">
+	  <title>Runtest_file_p Procedure</title>
+
+	  <para>Search <emphasis>runtest</emphasis>s for
+	  <emphasis>testcase</emphasis> and return <emphasis>1</emphasis> if
+	  found, <emphasis>0</emphasis> if not. <emphasis>runtests</emphasis>
+	  is a list of two elements.  The first is the pathname of the
+	  testsuite expect script running.  The second is a copy of what was on
+	  the right side of the <emphasis>=</emphasis> if
+	  <programlisting>foo.exp="..."</programlisting>" was specified, or
+	  an empty string if no such argument is present. This is used by tools
+	  like compilers where each testcase is a file.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>runtest_file_p</function></funcdef>
+	    <paramdef><parameter>runtests</parameter>
+	    <parameter>testcase</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>runtests</parameter></term>
+	    <listitem><para>The pathname of the testsuite expect script
+	    running</para></listitem> 
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>testcase</parameter></term>
+	    <listitem><para>The test case filename.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=diff xreflabel="diff procedure">
+	  <title>Diff Procedure</title>
+
+	  <para>Compares the two files and returns a <emphasis>1</emphasis> if
+	  they match, or a <emphasis>0</emphasis> if they don't. If
+	  <symbol>verbose</symbol> is set, then it'll print the differences to
+	  the screen.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>diff</function></funcdef>
+	    <paramdef><parameter>file_1</parameter>
+	    <parameter>file_2</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>file_1</parameter></term>
+	    <listitem><para>The first file to compare.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>file_2</parameter></term>
+	    <listitem><para>The second file to compare.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=setenv xreflabel="setenv procedure">
+	  <title>Setenv Procedure</title>
+
+	  <para>Sets the environment variable <emphasis>var</emphasis> to the
+	  value <emphasis>val</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>setenv</function></funcdef>
+	    <paramdef><parameter>var</parameter>
+   	    <parameter>val</parameter></paramdef>
+	 </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para>The environment variable to set.</para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>val</parameter></term>
+	    <listitem><para>The value to set the variable to.</para></listitem>
+          </varlistentry>
+	</variablelist>
+
+	<sect3 id=unsetenv xreflabel="unsetenv procedure">
+	  <title>unsetenv Procedure</title>
+
+	  <para>Unsets the environment variable
+	  <emphasis>var</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>unsetenv</function></funcdef>
+	    <paramdef><parameter>var</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para>The environment variable to
+	    unset.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=getenv xreflabel="getenv procedure">
+	  <title>Getenv Procedure</title>
+
+	  <para>Returns the value of <emphasis>var</emphasis> in the
+	  environment if it exists, otherwise it returns NULL.
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>getenv</function></funcdef>
+	    <paramdef><parameter>var</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para>The environment variable to get the value
+	    of.</para></listitem>
+          </varlistentry>
+	</variablelist>
+
+	<sect3 id=prunesystemcrud xreflabel="prune_system_crud procedure">
+	  <title>Prune_system_crud Procedure</title>
+
+	  <para>For system <emphasis>system</emphasis>, delete text the host or
+	  target operating system might issue that will interfere with pattern
+	  matching of program output in <emphasis>text</emphasis>.  An example
+	  is the message that is printed if a shared library is out of
+	  date.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>prune_system_crud</function></funcdef>
+	    <paramdef><parameter>system</parameter>
+	    <parameter>test</parameter></paramdef>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>system</parameter></term>
+	    <listitem><para>The system error messages to look for to screen out
+	   .</para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>text</parameter></term>
+	    <listitem><para>The Tcl variable containing the
+	    text.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+	
+    </sect2>
+
+    <sect2 id=libgloss xreflabel="Libgloss">
+      <title>Libgloss, A Free BSP</title>
+
+      <para>Libgloss is a free <firstterm>BSP</firstterm> (Board Support
+      Package) commonly used with GCC and G++ to produce a fully linked
+      executable image for an embedded systems.</para>
+
+      <sect3 id=libglosslinkflags xreflabel="libgloss_link_flags procedure">
+        <title>Libgloss_link_flags Procedure</title>
+
+	<para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>libgloss_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=libglossincludeflags xreflabel="libgloss_include_flags
+	procedure">
+	  <title>Libgloss_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>libgloss_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=newliblinkflags xreflabel="newlib_link_flags procedure">
+	  <title>Newlib_link_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>newlib_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=newlibincludeflags xreflabel="newlib_include_flags
+	procedure">
+	  <title>Newlib_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>newlib_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=libioincludeflags xreflabel="libio_include_flags
+	procedure">
+	  <title>Libio_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>libio_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=libiolinkflags xreflabel="libio_link_flags procedure">
+	  <title>Libio_link_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>libio_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=gxxincludeflags xreflabel="g++_include_flags procedure">
+	  <title>G++_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>g++_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=gxxlinkflags xreflabel="g++_link_flags procedure">
+	  <title>G++_link_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>g++_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=libstdcxxincludeflags xreflabel="libstdc++_include_flags
+	procedure">
+	  <title>Libstdc++_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>libstdc++_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=libstdcxxlinkflags xreflabel="libstdc++_link_flags
+	procedure">
+	  <title>Libstdc++_link_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>libstdc++_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=getmultilibs xreflabel="get_multilibs procedure">
+	  <title>Get_multilibs Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>get_multilibs</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=findbinutilsprog xreflabel="find_binutils_prog procedure">
+	  <title>Find_binutils_prog Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>find_binutils_prog</function></funcdef>
+	    <paramdef><parameter>name</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=findgcc xreflabel="find_gcc procedure">
+	  <title>Find_gcc Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>find_gcc</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=findgcj xreflabel="find_gcj procedure">
+	  <title>Find_gcj Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>find_gcj</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=findgxx xreflabel="find_g++ procedure">
+	  <title>Find_g++ Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>find_g++</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=findg77 xreflabel="find_g77 procedure">
+	  <title>Find_g77 Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>find_g77</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=processmultiliboptions xreflabel="process_multilib_options
+	procedure">
+	  <title>Process_multilib_options Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>process_multilib_options</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=addmultiliboption xreflabel="add_multilib_option
+	procedure">
+	  <title>Add_multilib_option Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>add_multilib_option</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=findgas xreflabel="find_gas procedure">
+	  <title>Find_gas Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>find_gas</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=findld xreflabel="find_ld procedure">
+	  <title>Find_ld Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>find_ld</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+        </funcsynopsis>
+	</sect3>
+
+	<sect3 id=buildwrapper xreflabel="build_wrapper procedure">
+	  <title>Build_wrapper Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>build_wrapper</function></funcdef>
+	    <paramdef><parameter>gluefile</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>gluefile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=winsupincludeflags xreflabel="winsup_include_flags
+	procedure">
+	  <title>Winsup_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>winsup_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=winsuplinkflags xreflabel="winsup_link_flags procedure">
+	  <title>Winsup_link_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>winsup_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+    </sect2>
+
+    <sect2 id=debugprocs xreflabel="Debugging Procedures">
+      <title>Procedures for debugging your Tcl code.</title>
+
+      <para><filename>lib/debugger.exp</filename>defines these utility
+      procedures:</para>
+
+      <sect3 id=dumpvars xreflabel="dumpvars procedure">
+        <title>Dumpvars Procedure</title>
+
+	<para>This takes a csh style regular expression (glob rules) and prints
+	the values of the global variable names that match.  It is abbreviated
+	as <emphasis>dv</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>dumpvars</function></funcdef>
+	    <paramdef><parameter>vars</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>vars</parameter></term>
+	    <listitem><para>The variables to dump.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=dumplocals xreflabel="dumplocals procedure">
+	  <title>Dumplocals Procedure</title>
+
+	  <para>This takes a csh style regular expression (glob rules) and
+	  prints the values of the local variable names that match. It is
+	  abbreviated as <emphasis>dl</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>dumplocals</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=dumprocs xreflabel="dumprocs procedure">
+	  <title>Dumprocs Procedure</title>
+
+	  <para>This takes a csh style regular expression (glob rules) and
+	  prints the body of all procs that match. It is abbreviated as
+	  <emphasis>dp</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>dumprocs</function></funcdef>
+	    <paramdef><parameter>pattern</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>pattern</parameter></term>
+	    <listitem><para>The csh "glob" style pattern to look
+	    for.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=dumpwatch xreflabel="dumpwatch procedure">
+	  <title>Dumpwatch Procedure</title>
+
+	  <para>This takes a csh style regular expression (glob rules) and
+	  prints all the watchpoints. It is abbreviated as
+	  <emphasis>dw</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>dumpwatch</function></funcdef>
+	    <paramdef><parameter>pattern</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>pattern</parameter></term>
+	    <listitem><para>The csh "glob" style pattern to look
+	    for.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=watcharray xreflabel="watcharray procedure">
+	  <title>Watcharray Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>watcharray</function></funcdef>
+	    <paramdef><parameter>element</parameter>
+		<parameter>type</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>type</parameter></term>
+	    <listitem><para>The csh "glob" style pattern to look
+	    for.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=watchvar xreflabel="watchvar procedure">
+	  <title>Watchvar Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>watchvar</function></funcdef>
+	    <paramdef><parameter>var</parameter>
+		<parameter>type</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=watchunset xreflabel="watchunset procedure">
+	  <title>Watchunset Procedure</title>
+
+	  <para>This breaks program execution when the variable
+	  <symbol>var</symbol> is unset. It is abbreviated as
+	  <emphasis>wu</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>watchunset</function></funcdef>
+	    <paramdef><parameter>arg</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=watchwrite xreflabel="watchwrite procedure">
+	  <title>Watchwrite Procedure</title>
+
+	  <para>This breaks program execution when the variable
+	  <symbol>var</symbol> is written. It is abbreviated as
+	  <emphasis>ww</emphasis>.</para> 
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>watchwrite</function></funcdef>
+	    <paramdef><parameter>var</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para>The variable to watch.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>	
+
+	<sect3 id=watchread xreflabel="watchread procedure">
+	  <title>Watchread Procedure</title>
+
+	  <para>This breaks program execution when the variable
+	  <symbol>var</symbol> is read. It is abbreviated as
+	  <emphasis>wr</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>watchread</function></funcdef>
+	    <paramdef><parameter>var</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para>The variable to watch.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=watchdel xreflabel="watchdel procedure">
+	  <title>Watchdel Procedure</title>
+
+	  <para>This deletes a the watchpoint from the watch list. It is
+	  abbreviated as <emphasis>wd</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>watchdel</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=print xreflabel="print procedure">
+	  <title>Print Procedure</title>
+
+	  <para>This prints the value of the variable
+	  <parameter>var</parameter>. It is abbreviated as
+	  <emphasis>p</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>print</function></funcdef>
+	    <paramdef><parameter>var</parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+	<sect3 id=quit xreflabel="quit procedure">
+	  <title>Quit Procedure</title>
+
+	  <para>This makes runtest exit. It is abbreviated as
+	  <emphasis>q</emphasis>.</para>
+
+	<funcsynopsis role="tcl"> 
+            <funcdef><function>quit</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect3>
+
+    </sect2>
+
+  </sect1>
+
+   <sect1 id=filemap>
+    <title>File Map</title>
+
+    <para>This is a map of the files in DejaGnu.</para>
+
+    <itemizedlist>
+      <listitem><para>runtest</para></listitem>
+      <listitem><para>runtest.exp</para></listitem>
+      <listitem><para>stub-loader.c</para></listitem>
+      <listitem><para>testglue.c</para></listitem>
+      <listitem><para>config</para></listitem>
+      <listitem><para>baseboards</para></listitem>
+      <listitem><para>lib/debugger.exp</para></listitem>
+      <listitem><para>lib/dg.exp</para></listitem>
+      <listitem><para>lib/framework.exp</para></listitem>
+      <listitem><para>lib/ftp.exp</para></listitem>
+      <listitem><para>lib/kermit.exp</para></listitem>
+      <listitem><para>lib/libgloss.exp</para></listitem>
+      <listitem><para>lib/mondfe.exp</para></listitem>
+      <listitem><para>lib/remote.exp</para></listitem>
+      <listitem><para>lib/rlogin.exp</para></listitem>
+      <listitem><para>lib/rsh.exp</para></listitem>
+      <listitem><para>lib/standard.exp</para></listitem>
+      <listitem><para>lib/target.exp</para></listitem>
+      <listitem><para>lib/targetdb.exp</para></listitem>
+      <listitem><para>lib/telnet.exp</para></listitem>
+      <listitem><para>lib/tip.exp</para></listitem>
+      <listitem><para>lib/util-defs.exp</para></listitem>
+      <listitem><para>lib/utils.exp</para></listitem>
+      <listitem><para>lib/xsh.exp</para></listitem>
+    </itemizedlist>
+
+  </sect1>
+
+</chapter>
diff --git a/doc/runtest.1 b/doc/runtest.1
new file mode 100644
index 0000000..2c3a357
--- /dev/null
+++ b/doc/runtest.1
@@ -0,0 +1,119 @@
+.TH runtest 1 "08 Dec 1998"
+.SH NAME
+runtest \- the DejaGnu test driver program
+.SH SYNOPSIS
+.B runtest
+[ options ]
+.SH DESCRIPTION
+.I DejaGnu
+is a framework for running test suites on GNU tools. It is written in
+expect, which uses TCL (Tool command language).  
+.B runtest
+is the test driver program; use it to control what tests to run, 
+and variations on how to run them.
+
+You can find a comprehensive description of DejaGnu and \fBruntest\fR in
+.I
+The DejaGnu Testing Framework
+or its Info version,
+.BR dejagnu.info .
+.SH OPTIONS
+.TP
+.B --all
+Print all test output to screen. By default, only unexpected results are 
+displayed.
+.TP
+.BI --baud \ rate
+Set the baud rate for a serial line connection. Some serial interface
+programs (like \fBtip\fR) don't use this value but instead use a separate
+initialization file.
+.TP
+.BI --connect \ type
+The type of connection to use.  The choices are 
+.BR rlogin , 
+.BR telnet ,
+.BR rsh , 
+.BR kermit , 
+.BR tip
+and
+.BR mondfe .
+.TP
+.B --debug
+Turn on
+.B expect
+internal debugging output. All output is logged to
+a file called \fBdbg.out\fR.
+The output of the \fB--strace\fR also goes into this file.
+.TP
+.B --help
+Prints out a help screen and then exits.
+.TP
+.BI --host \ type
+The configuration string for the host.
+.TP
+.BI --ignore \ test1.exp\ test2.exp\ ...
+Do not run the specified tests.
+.BI --mail \ \'name1\ name2\ ...\'
+Electronic mail addresses to receive test results.
+.TP
+.BI --name \ hostname
+The network hostname of the target board.
+.TP
+.BI --objdir \ path
+\fIpath\fR is a directory containing compiled test code.
+.TP
+.BI --outdir \ directory
+The name of a directory for test log output.
+.TP
+.B --reboot
+Reboot the target board when \fBruntest\fR initializes
+(if supported).
+.TP
+.BI --srcdir \ path
+\fIpath\fR is a directory containing test directories.
+.TP
+.BI --strace \ N
+Turns on
+.B expect
+internal tracing to \fIN\fR levels deep.
+.TP 
+.BI --target \ type
+The configuration string for the target.
+.TP 
+.BI --tool \ toolname
+Specify the tool to be tested.  \fItoolname\fR controls the test suite 
+applied, and the associated initialization module.
+.TP
+.B --verbose,\ -v
+Turns on more debugging output from test cases and DejaGnu utility code. 
+Use more than once to increase output further.
+.TP
+.B --version,\ -V
+Prints out the versions of DejaGnu, expect and Tcl.
+.TP
+.B -D[number]
+Activate the Tcl debugger.\fBnumber\fR can be either 1 or 0. If it is
+1, then the expect shell will break when it starts to run. All ^C's
+drop DejaGnu back to the debugger prompt. A 0 starts DejaGnu like
+normal, but a ^C drops to the debugger prompt.
+.TP 0
+Any file name on the command line is assumed to be a subset
+of the test names to run.  Usually these are the names of the
+expect test driver, ie... special.exp.
+
+Makefile style variables are used to specify tool names and their
+flags; these and other configuration dependent values are saved in the
+file \fBsite.exp\fR, created during configuration.
+.SH EXIT CODES
+.B runtest
+sets the exit code to 1 if any of the tests failed, or
+sets it to 0 if all the tests passed.
+.SH SEE ALSO
+.I The DejaGnu Testing Framework
+.RB ( dejagnu.info ).
+This is the DejaGnu manual; its source is the SGML files
+.B
+doc/*.sgml.
+in the DejaGnu distribution.
+.SH AUTHOR
+Rob Savoye (rob@welcomehome.org)
diff --git a/doc/user.sgml b/doc/user.sgml
new file mode 100644
index 0000000..2154d74
--- /dev/null
+++ b/doc/user.sgml
@@ -0,0 +1,2355 @@
+  <chapter id=runningtests>
+    <title>Running Tests</title>
+
+    <para>There are two ways to execute a test suite. The most
+    common way is when there is existing support in the
+    <filename>Makefile</filename>. This support consists of a
+    <emphasis>check</emphasis> target. The other way is to execute the
+    <command>runtest</command> program directly. To run
+    <command>runtest</command> directcly from the command line requires
+    either all the correct options, or the <xref linkend=local> must be setup
+    correctly.</para>
+
+    <sect1 id=makecheck xreflabel="Make Check">
+      <title>Make check</title>
+
+      <para>To run tests from an existing collection, first use
+      <command>configure</command> as usual to set up the
+      build directory. Then try typing:</para>
+
+      <screen>
+      make check
+      </screen>
+
+      <para>If the <emphasis>check</emphasis> target exists, it
+      usually saves you some trouble. For instance, it can set up any
+      auxiliary programs or other files needed by the tests. The most
+      common file the check builds is the
+      <emphasis>site.exp</emphasis>. The site.exp file contains
+      various variables that DejaGnu used to dertermine the
+      configuration of the program being tested. This is mostly for
+      supporting remote testing.</para>
+
+      <para>The <emphasis>check</emphasis> target is supported by GNU
+      <productname>Automake</productname>. To have DejaGnu support added to your
+      generated <filename>Makefile.in</filename>, just add the keyword
+      dejagnu to the AUTOMAKE_OPTIONS variable in your
+      <filename>Makefile.am</filename> file.</para>
+
+      <para>Once you have run <emphasis>make check</emphasis> to build
+      any auxiliary files, you can invoke the test driver
+      <command>runtest</command> directly to repeat the tests.
+      You will also have to execute <command>runtest</command>
+      directly for test collections with no
+      <emphasis>check</emphasis> target in the
+      <filename>Makefile</filename>.</para>
+
+    </sect1>
+    
+    <sect1 id=runtest xreflabel="Runtest">
+      <title>Runtest</title>
+
+      <para><command>runtest</command> is the executable test driver
+      for DejaGnu. You can specify two kinds of things on the
+      <command>runtest</command> command line: command line options,
+      and Tcl variables for the test scripts. The options are listed
+      alphabetically below.</para>
+
+      <para><command>runtest</command> returns an exit code of
+      <emphasis>1</emphasis> if any test has an unexpected result; otherwise
+      (if all tests pass or fail as expected) it returns <emphasis>0</emphasis>
+      as the exit code.</para>
+
+      <sect2 id=outputs xreflabel="Output States">
+        <title>Output States</title>
+
+	<para><filename>runtest</filename> flags the outcome of each
+	test as one of these cases. <xref linkend=posix> for a
+	discussion of how POSIX specifies the meanings of these
+	cases.</para>
+
+        <variablelist>
+        <varlistentry>
+          <term>PASS</term>
+          <listitem><para>The most desirable outcome: the test succeeded, and
+          was expected to succeed.</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>XPASS</term>
+          <listitem><para>A pleasant kind of failure: a test was expected to
+          fail, but succeeded. This may indicate progress; inspect the test
+          case to determine whether you should amend it to stop expecting
+          failure.</para></listitem>
+	</varlistentry>
+ 
+	<varlistentry>
+	  <term>FAIL</term>
+          <listitem><para>A test failed, although it was expected to succeed.
+          This may indicate regress; inspect the test case and the failing
+          software to ocate the bug.</para></listitem>
+	</varlistentry>
+ 
+	<varlistentry>
+	  <term>XFAIL</term>
+          <listitem><para>A test failed, but it was expected to fail.  This
+          result indicates no change in a known bug.  If a test fails because
+          the operating system where the test runs lacks some facility required
+          by the test, the outcome is <emphasis>UNSUPPORTED</emphasis>
+          instead.</para></listitem>
+	</varlistentry>
+ 
+	<varlistentry>
+	  <term>UNRESOLVED</term>
+          <listitem><para>Output from a test requires manual inspection; the
+          test suite could not automatically determine the outcome.  For
+          example, your tests can report this outcome is when a test does not
+          complete as expected.</para></listitem>
+	</varlistentry>
+ 
+	<varlistentry>
+	  <term>UNTESTED</term>
+          <listitem><para>A test case is not yet complete, and in particular
+          cannot yet produce a <emphasis>PASS</emphasis> or
+          <emphasis>FAIL</emphasis>. You can also use this outcome in dummy
+          ``tests'' that note explicitly the absence of a real test case for a
+          particular property.</para></listitem>
+	</varlistentry>
+ 
+	<varlistentry>
+	  <term>UNSUPPORTED</term>
+          <listitem><para>A test depends on a conditionally available feature
+          that does not exist (in the configured testing environment).  For
+          example, you can use this outcome to report on a test case that does
+          not work on a particular target because its operating system support
+          does not include a required subroutine.</para></listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>runtest may also display the following messages:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term>ERROR</term>
+          <listitem><para>Indicates a major problem (detected by the test case
+          itself) in running the test. This is usually an unrecoverable error,
+          such as a missing file or loss of communication to the target. (POSIX
+          test suites should not emit this message; use
+          <emphasis>UNSUPPORTED</emphasis>, <emphasis>UNTESTED</emphasis>, or
+          <emphasis>UNRESOLVED</emphasis> instead, as
+          appropriate.)</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term>WARNING</term>
+          <listitem><para>Indicates a possible problem in running the
+          test. Usually warnings correspond to recoverable errors, or display
+          an important message about the following tests.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+        <term>NOTE</term>
+        <listitem><para>An informational message about the test
+        case.</para></listitem>
+	</varlistentry>
+      </variablelist>
+
+    </sect2>
+
+    <sect2 id=invoking xreflabel="Invoking Runtest">
+      <title>Invoking Runtest</title>
+
+      <para>This is the full set of command line options that
+      <filename>runtest</filename> recognizes. Arguments may be
+      abbreviated to the shortest unique string.</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><option>--all</option> (-a)</term>
+	  <listitem><para>Display all test output. By default,
+	  <emphasis>runtest</emphasis> shows only the output of tests that
+	  produce unexpected results; that is, tests with status
+	  <emphasis>FAIL</emphasis> (unexpected failure),
+	  <emphasis>XPASS</emphasis> (unexpected success), or
+	  <emphasis>ERROR</emphasis> (a severe error in the test case
+	  itself). Specify <emphasis>--all</emphasis> to see output for tests
+	  with status <emphasis>PASS</emphasis> (success, as expected)
+	  <emphasis>XFAIL</emphasis> (failure, as expected), or
+	  <emphasis>WARNING</emphasis> (minor error in the test case
+	  itself).</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--build [string]</option></term>
+	  <listitem><para><emphasis>string</emphasis> is a full configuration
+	  ``triple'' name as used by <command>configure</command>. This
+	  is the type of machine DejaGnu and the tools to be tested are built
+	  on. For a normal cross this is the same as the host, but for a
+	  canadian cross, they are seperate.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--host [string]</option></term>
+	  <listitem><para><symbol>string</symbol> is a full configuration
+	  ``triple'' name as used by <emphasis>configure</emphasis>.  Use this
+	  option to override the default string recorded by your
+	  configuration's choice of host.  This choice does not change how
+	  anything is actually configured unless --build is also specified; it
+	  affects <emphasis>only</emphasis> DejaGnu procedures that compare the
+	  host string with particular values.  The procedures
+	  <emphasis>ishost</emphasis>, <emphasis>istarget</emphasis>,
+	  <emphasis>isnative</emphasis>, and <emphasis>setup</emphasis>xfail}
+	  are affected by <emphasis>--host</emphasis>. In this usage,
+	  <emphasis>host</emphasis> refers to the machine that the tests are to
+	  be run on, which may not be the same as the
+	  <emphasis>build</emphasis> machine. If <emphasis>--build</emphasis>
+	  is also specified, then <emphasis>--host</emphasis> refers to the
+	  machine that the tests wil, be run on, not the machine DejaGnu is run
+	  on.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--host_board [name]</option></term>
+	  <listitem><para>The host board to use.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--target [string]</option></term>
+	  <listitem><para>Use this option to override the default setting
+	  (running native tests). <emphasis>string</emphasis> is a full
+	  configuration ``triple'' name of the form
+	  <emphasis>cpu-vendor-os</emphasis> as used by
+	  <command>configure</command>. This option changes the
+	  configuration <emphasis>runtest</emphasis> uses for the default tool
+	  names, and other setup information.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--debug</option> (-de)</term>
+	  <listitem><para>Turns on the <emphasis>expect</emphasis> internal
+	  debugging output. Debugging output is displayed as part of the
+	  <emphasis>runtest</emphasis> output, and logged to a file called
+	  <filename>dbg.log</filename>. The extra debugging output does
+	  <emphasis>not</emphasis> appear on standard output, unless the
+	  verbose level is greater than 2 (for instance, to see debug output
+	  immediately, specify <emphasis>--debug</emphasis>-v -v}). The
+	  debugging output shows all attempts at matching the test output of
+	  the tool with the scripted patterns describing expected output.  The
+	  output generated with <emphasis>--strace</emphasis> also goes into
+	  <filename>dbg.log</filename>.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--help</option> (-he)</term>
+	  <listitem><para>Prints out a short summary of the
+	  <emphasis>runtest</emphasis> options, then exits (even if you also
+	  specify other options).</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--ignore [name(s)] </option></term>
+	  <listitem><para>The names of specific tests to
+	  ignore.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--objdir [path]</option></term>
+	  <listitem><para>Use <emphasis>path</emphasis> as the top directory
+	  containing any auxiliary compiled test code. This defaults to
+	  <filename>.</filename>.  Use this option to locate pre-compiled test
+	  code.  You can normally prepare any auxiliary files needed with
+	  <emphasis>make</emphasis>.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--outdir [path]</option></term>
+	  <listitem><para>Write output logs in directory
+	  <filename>path</filename>.  The default is <emphasis>.},
+	  the</emphasis> directory where you start
+	  <emphasis>runtest</emphasis>. This option affects only the summary
+	  and the detailed log files
+	  <filename>tool.sum</filename> and
+	  <filename>tool.log</filename>. The DejaGnu debug
+	  log <filename>dbg.log</filename> always appears (when requested) in
+	  the local directory.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--reboot [name]</option></term>
+	  <listitem><para>Reboot the target board when
+	  <emphasis>runtest</emphasis> initializes. Usually, when running tests
+	  on a separate target board, it is safer to reboot the target to be
+	  certain of its state.  However, when developing test scripts,
+	  rebooting takes a lot of time.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--srcdir [path]</option></term>
+	  <listitem><para>Use <filename>path</filename> as the top directory
+	  for test scripts to run. <emphasis>runtest</emphasis> looks in this
+	  directory for any subdirectory whose name begins with the toolname
+	  (specified with <emphasis>--tool</emphasis>). For instance, with
+	  <emphasis>--tool</emphasis>gdb}, <emphasis>runtest</emphasis> uses
+	  tests in subdirectories <filename>gdb.*</filename> (with the usual
+	  shell-like filename expansion).  If you do not use
+	  <emphasis>--srcdir</emphasis>, <emphasis>runtest</emphasis> looks for
+	  test directories under the current working
+	  directory.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--strace [number]</option></term>
+	  <listitem><para>Turn on internal tracing for
+	  <emphasis>expect</emphasis>, to n levels deep. By adjusting the
+	  level, you can control the extent to which your output expands
+	  multi-level Tcl statements.  This allows you to ignore some levels of
+	  <emphasis>case</emphasis> or <emphasis>if</emphasis> statements.
+	  Each procedure call or control structure counts as one ``level''. The
+	  output is recorded in the same file, <filename>dbg.log</filename>,
+	  used for output from <emphasis>--debug</emphasis>.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--connect [program]</option></term>
+	  <listitem><para>Connect to a target testing environment as specified
+	  by <emphasis>type</emphasis>, if the target is not the computer
+	  running <emphasis>runtest</emphasis>.  For example, use
+	  <emphasis>--connect</emphasis> to change the program used to connect
+	  to a ``bare board'' boot monitor.  The choices for
+	  <emphasis>type</emphasis> in the DejaGnu 1.4 distribution are
+	  <emphasis>rlogin</emphasis>, <emphasis>telnet</emphasis>,
+	  <emphasis>rsh</emphasis>, <emphasis>tip</emphasis>,
+	  <emphasis>kermit</emphasis>, and <emphasis>mondfe</emphasis>.</para>
+
+	  <para>The default for this option depends on the configuration most
+	  convenient communication method available, but often other
+	  alternatives work as well; you may find it useful to try alternative
+	  connect methods if you suspect a communication problem with your
+	  testing target.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--baud [number]</option></term>
+	  <listitem><para>Set the default baud rate to something other than
+	  9600. (Some serial interface programs, like <emphasis>tip</emphasis>,
+	  use a separate initialization file instead of this
+	  value.)</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--target_board [name(s)]</option></term>
+	  <listitem><para>The list of target boards to run tests
+	  on.</para></listitem>
+	</varlistentry>
+	
+        <varlistentry id=tool-opt>
+          <term><option>--tool[name(s)]</option></term>
+	  <listitem><para>Specifies which test suite to run, and what
+	  initialization module to use. <option>--tool</option> is used
+	  <emphasis>only</emphasis> for these two purposes. It is
+	  <emphasis>not</emphasis> used to name the executable program to
+	  test. Executable tool names (and paths) are recorded in
+	  <filename>site.exp</filename> and you can override them by specifying
+	  Tcl variables on the command line.</para>
+	  
+	  <para>For example, including "<option>--tool</option> gcc" on the
+	  <emphasis>runtest</emphasis> command line runs tests from all test
+	  subdirectories whose names match <filename>gcc.*</filename>, and uses
+	  one of the initialization modules named
+	  <filename>config/*-gcc.exp</filename>. To specify the name of the
+	  compiler (perhaps as an alternative path to what
+	  <emphasis>runtest</emphasis> would use by default), use
+	  <emphasis>GCC=binname</emphasis> on the <emphasis>runtest</emphasis>
+	  command line.</para></listitem>
+	</varlistentry>
+        
+	<varlistentry>
+          <term><option>--tool_exec [name]</option></term>
+	  <listitem><para>The path to the tool executable to
+	  test.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--tool_opts [options]</option></term>
+	  <listitem><para>A list of additional options to pass to the
+	  tool.</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+          <term><option>--verbose</option> (-v)</term>
+	  <listitem><para>Turns on more output. Repeating this option increases
+          the amount of output displayed. Level one (<emphasis>-v</emphasis>)
+          is simply test output. Level two (<emphasis>-v</emphasis>-v}) shows
+          messages on options, configuration, and process control.  Verbose
+          messages appear in the detailed (<filename>*.log</filename>) log
+          file, but not in the summary (<filename>*.sum</filename>) log
+          file.</para></listitem>
+	</varlistentry>
+        
+	<varlistentry>
+          <term><option>--version</option> (-V)</term>
+	  <listitem><para>Prints out the version numbers of DejaGnu,
+	  <emphasis>expect</emphasis> and Tcl, and exits without running any
+	  tests.</para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><option>--D[0-1]</option></term>
+	  <listitem><para>Start the internal Tcl debugger. The Tcl debugger
+	  supports breakpoints, single stepping, and other common debugging
+	  activities. See the document "Debugger for Tcl Applications} by Don
+	  Libes. (Distributed in PostScript form with
+	  <emphasis>expect</emphasis> as the file
+	  <filename>expect/tcl-debug.ps.</filename>. If you specify
+	  <emphasis>-D1</emphasis>, the <emphasis>expect</emphasis> shell stops
+	  at a breakpoint as soon as DejaGnu invokes it. If you specify
+	  <emphasis>-D0</emphasis>, DejaGnu starts as usual, but you can enter
+	  the debugger by sending an interrupt (e.g. by typing
+	  <keycombo><keycap>C</keycap><keycap>c</keycap></keycombo>).
+	  </para></listitem>
+	</varlistentry>
+
+        <varlistentry>
+          <term><filename>testfile</filename>.exp[=arg(s)]</term>
+	  <listitem><para>Specify the names of testsuites to run. By default,
+	  <emphasis>runtest</emphasis> runs all tests for the tool, but you can
+	  restrict it to particular testsuites by giving the names of the
+	  <emphasis>.exp expect</emphasis> scripts that control
+	  them. <emphasis>testsuite</emphasis>.exp may not include path
+	  information; use plain filenames.</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+          <term><filename>testfile</filename>.exp="testfile1 ..."</term> 
+	  <listitem><para>Specify a subset of tests in a suite to run. For
+	  compiler or assembler tests, which often use a single
+	  <emphasis>.exp</emphasis> script covering many different source
+	  files, this option allows you to further restrict the tests by
+	  listing particular source files to compile. Some tools even support
+	  wildcards here.  The wildcards supported depend upon the tool, but
+	  typically they are <emphasis>?</emphasis>, <emphasis>*</emphasis>,
+	  and <emphasis>[chars]</emphasis>.</para></listitem>
+	</varlistentry>
+
+	<varlistentry>
+          <term><symbol>tclvar</symbol>=value</term>
+	  <listitem><para>You can define Tcl variables for use by your test
+	  scripts in the same style used with <emphasis>make</emphasis> for
+	  environment variables.  For example, <emphasis>runtest
+	  GDB=gdb.old</emphasis> defines a variable called
+	  <command>GDB</command>; when your scripts refer to
+	  <symbol>$GDB</symbol> in this run, they use the value
+	  <emphasis>gdb.old</emphasis>.</para>
+
+	  <para>The default Tcl variables used for most tools are defined in
+	  the main DejaGnu <emphasis>Makefile</emphasis>; their values are
+	  captured in the <filename>site.exp</filename> file.</para></listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+
+       <sect2 id=common xreflabel="Common Operations">
+        <title>Common Options</title>
+	
+	<para>Typically, you don't need must to use any command-line options.
+	<option>--tool</option> used is only required when there are more than
+	one test suite in the same directory. The default options are in the
+	local site.exp file, created by "make site.exp".</para>
+
+	<para>For example, if the directory <filename>gdb/testsuite</filename>
+	contains a collection of DejaGnu tests for GDB, you can run them like
+	this:</para>
+
+        <screen>
+	  eg$ cd gdb/testsuite
+	  eg$ runtest --tool gdb
+	</screen>
+
+	<para>Test output follows, ending with:</para>
+
+	<screen>
+		=== gdb Summary ===
+
+		# of expected passes 508
+		# of expected failures 103
+		/usr/latest/bin/gdb version 4.14.4 -nx
+	</screen>
+
+	<para>You can use the option <emphasis>--srcdir</emphasis> to point to 
+	some other directory containing a collection of tests:</para>
+
+	<screen>
+	  eg$ runtest--srcdir /devo/gdb/testsuite
+	</screen>
+
+	<para>By default, <command>runtest</command> prints only the
+	names of the tests it runs, output from any tests that have unexpected
+	results, and a summary showing how many tests passed and how many
+	failed.  To display output from all tests (whether or not they behave
+	as expected), use the <emphasis>--all</emphasis> option.  For more
+	verbose output about processes being run, communication, and so on, use
+	<emphasis>--verbose</emphasis>. To see even more output, use multiple
+	<emphasis>--verbose</emphasis> options. for a more detailed explanation
+	of each <command>runtest</command> option.
+
+	<para>Test output goes into two files in your current directory:
+	summary output in <filename>tool.sum</filename>,
+	and detailed output in <filename>
+	tool.log</filename>. (<emphasis>tool</emphasis>
+	refers to the collection of tests; for example, after a run with
+	<emphasis>--tool</emphasis> gdb, look for output files
+	<filename>gdb.sum</filename> and <filename>gdb.log</filename>.)
+      </sect2>
+    </sect1>  
+
+    <sect1 id=outputfiles xreflabel="Output Files">
+
+    <title>The files DejaGnu produces.</title>
+
+    <para>DejaGnu always writes two kinds of output files: summary
+    logs and detailed logs.  The contents of both of these are
+    determined by your tests.</para>
+
+    <para>For troubleshooting, a third kind of output file is useful:
+    use <option>--debug</option> to request an output file showing
+    details of what <productname>Expect</productname> is doing
+    internally.</para>
+
+    <sect2 id=sum xreflabel="Summary File">
+      <title>Summary File</title>
+
+      <para>DejaGnu always produces a summary output file
+      <filename>tool.sum</filename>. This summary shows the names of
+      all test files run; for each test file, one line of output from
+      each <command>pass</command> command (showing status
+      <emphasis>PASS</emphasis> or <emphasis>XPASS</emphasis>) or
+      <command>fail</command> command (status
+      <emphasis>FAIL</emphasis> or <emphasis>XFAIL</emphasis>);
+      trailing summary statistics that count passing and failing tests
+      (expected and unexpected); and the full pathname and version
+      number of the tool tested.  (All possible outcomes, and all
+      errors, are always reflected in the summary output file,
+      regardless of whether or not you specify <option>--all</option>.)
+
+      <para>If any of your tests use the procedures
+      <command>unresolved</command>, <command>unsupported</command>,
+      or <command>runtested</command>, the summary output also
+      tabulates the corresponding outcomes.</para>
+
+      <para>For example, after <command>runtest --tool
+      binutils</command>, look for a summary log in
+      <filename>binutils.sum</filename>. Normally, DejaGnu writes this
+      file in your current working directory; use the
+      <option>--outdir</option> option to select a different
+      directory.</para>
+
+      <example>
+        <title>Here is a short sample summary log</title>
+
+	<screen>
+	Test Run By rob on Mon May 25 21:40:57 PDT 1992
+		 === gdb tests ===
+	Running ./gdb.t00/echo.exp ...
+	PASS:   Echo test
+	Running ./gdb.all/help.exp ...
+	PASS:   help add-symbol-file
+	PASS:   help aliases
+	PASS:   help breakpoint "bre" abbreviation
+	FAIL:   help run "r" abbreviation
+	Running ./gdb.t10/crossload.exp ...
+	PASS:   m68k-elf (elf-big) explicit format; loaded
+	XFAIL:  mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed C types 
+                === gdb Summary ===
+	# of expected passes 5
+	# of expected failures 1
+	# of unexpected failures 1
+	/usr/latest/bin/gdb version 4.6.5 -q
+      </screen>
+    </example>
+
+    </sect2>
+
+    <sect2 id=log xreflabel="Log File">
+      <title>Log File</title>
+
+      <para>DejaGnu also saves a detailed log file
+      <filename>tool.log</filename>, showing any output generated by
+      tests as well as the summary output. For example, after
+      <command>runtest --tool binutils</command>, look for a detailed
+      log in <filename>binutils.log</filename>. Normally, DejaGnu
+      writes this file in your current working directory; use the
+      <option>--outdir</option> option to select a different
+      directory.</para>
+
+
+      <example>
+        <title>Here is a brief example showing a detailed log for
+        <productname>G++</productname> tests</title>
+
+	<screen>
+	Test Run By rob on Mon May 25 21:40:43 PDT 1992
+
+                === g++ tests ===
+
+	--- Running ./g++.other/t01-1.exp ---
+        PASS:   operate delete
+
+	--- Running ./g++.other/t01-2.exp ---
+        FAIL:   i960 bug EOF
+	p0000646.C: In function `int  warn_return_1 ()':
+	p0000646.C:109: warning: control reaches end of non-void function
+	p0000646.C: In function `int  warn_return_arg (int)':
+	p0000646.C:117: warning: control reaches end of non-void function
+	p0000646.C: In function `int  warn_return_sum (int, int)':
+	p0000646.C:125: warning: control reaches end of non-void function
+	p0000646.C: In function `struct foo warn_return_foo ()':
+	p0000646.C:132: warning: control reaches end of non-void function
+
+	--- Running ./g++.other/t01-4.exp ---
+        FAIL:   abort
+	900403_04.C:8: zero width for bit-field `foo'
+	--- Running ./g++.other/t01-3.exp ---
+        FAIL:   segment violation
+	900519_12.C:9: parse error before `;'
+	900519_12.C:12: Segmentation violation
+	/usr/latest/bin/gcc: Internal compiler error: program cc1plus got fatal signal
+
+                === g++ Summary ===
+
+	# of expected passes 1
+	# of expected failures 3
+	/usr/latest/bin/g++ version cygnus-2.0.1
+	</screen>
+	</example>
+
+    </sect2>
+
+    <sect2 id=debugfile xreflabel="Debug Log File">
+      <title>Debug Log File</title>
+
+      <para>With the <option>--debug</option> option, you can request
+      a log file showing the output from
+      <productname>Expect</productname> itself, running in debugging
+      mode. This file (<filename>dbg.log</filename>, in the directory
+      where you start <command>runtest</command>) shows each pattern
+      <productname>Expect</productname> considers in analyzing test
+      output.</para>
+
+      <para>This file reflects each <command>send</command> command,
+      showing the string sent as input to the tool under test; and
+      each <productname>Expect</productname> command, showing each
+      pattern it compares with the tool output.</para>
+
+      <example>
+        <title>The log messages begin with a message of the form</title>
+
+	<screen>
+
+	expect: does {<symbol>tool output</symbol>} (spawn_id <symbol>n</symbol>)
+	 match pattern {<emphasis>expected pattern</emphasis>}?
+
+        </screen>
+      </example>
+
+      <para>For every unsuccessful match,
+      <productname>Expect</productname> issues a
+      <emphasis>no</emphasis> after this message; if other patterns
+      are specified for the same <productname>Expect</productname>
+      command, they are reflected also, but without the first part of
+      the message (<emphasis>expect... match pattern</emphasis>).</para>
+
+      <para>When <productname>Expect</productname> finds a match, the
+      log for the successful match ends with <emphasis>yes</emphasis>,
+      followed by a record of the <productname>Expect</productname>
+      variables set to describe a successful match.</para>
+
+      <example>
+        <title>Here is an excerpt from the debugging log for a
+        <productname>GDB</productname> test:</title>
+
+	<screen>
+	send: sent {break gdbme.c:34\n} to spawn id 6
+	expect: does {} (spawn_id 6) match pattern {Breakpoint.*at.* file
+	gdbme.c, line 34.*\(gdb\) $}? no
+	{.*\(gdb\) $}? no
+	expect: does {} (spawn_id 0) match pattern {return} ? no
+	{\(y or n\) }? no
+	{buffer_full}? no
+	{virtual}? no
+	{memory}? no
+	{exhausted}? no
+	{Undefined}? no
+	{command}? no
+	break gdbme.c:34
+	Breakpoint 8 at 0x23d8: file gdbme.c, line 34.
+	(gdb) expect: does {break gdbme.c:34\r\nBreakpoint 8 at 0x23d8: 
+	file gdbme.c, line 34.\r\n(gdb) } (spawn_id 6) match pattern
+	{Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $}? yes
+	expect: set expect_out(0,start) {18}
+	expect: set expect_out(0,end) {71}
+	expect: set expect_out(0,string) {Breakpoint 8 at 0x23d8: file
+	gdbme.c, line 34.\r\n(gdb) }
+	epect: set expect_out(spawn_id) {6}
+	expect: set expect_out(buffer) {break gdbme.c:34\r\nBreakpoint 8
+	at 0x23d8: file gdbme.c, line 34.\r\n(gdb) }
+        PASS:   70      0       breakpoint line number in file
+	</screen>
+	</example>
+
+	<para>This example exhibits three properties of
+	<productname>Expect</productname> and
+	<productname>DejaGnu</productname> that might be surprising at
+	first glance:</para>
+
+	<itemizedlist mark="bullet">
+	<listitem><para>Empty output for the first attempted match.  The
+	first set of attempted matches shown ran against the output
+	<emphasis>{}</emphasis> --- that is, no
+	output. <productname>Expect</productname> begins 
+	attempting to match the patterns supplied immediately; often,
+	the first pass is against incomplete output (or completely
+	before all output, as in this case).</para></listitem>
+
+	<listitem><para>Interspersed tool output.  The beginning of
+	the log entry for the second attempted match may be hard to
+	spot: this is because the prompt <emphasis>{(gdb) }</emphasis>
+	appears on the same line, just before the
+	<emphasis>expect:</emphasis> that marks the beginning of the
+	log entry.</para></listitem>
+
+	<listitem><para>Fail-safe patterns.  Many of the patterns
+	tested are fail-safe patterns provided by
+	<productname>GDB</productname> testing utilities, to reduce
+	possible indeterminacy.  It is useful to anticipate potential
+	variations caused by extreme system conditions
+	(<productname>GDB</productname> might issue the message
+	<emphasis>virtual memory exhausted</emphasis> in rare
+	circumstances), or by changes in the tested program
+	(<emphasis>Undefined command</emphasis> is the likeliest
+	outcome if the name of a tested command changes).</para>
+
+	<para>The pattern <emphasis>{return}</emphasis> is a
+	particularly interesting fail-safe to notice; it checks for an
+	unexpected <keycap>RET</keycap> prompt.  This may happen,
+	for example, if the tested tool can filter output through a
+	pager.</para>
+
+	<para>These fail-safe patterns (like the debugging log itself)
+	are primarily useful while developing test scripts.  Use the
+	<command>error</command> procedure to make the actions for
+	fail-safe patterns produce messages starting with
+	<emphasis>ERROR</emphasis> on standard output, and in the
+	detailed log file.</para></listitem>
+	</itemizedlist>
+    </sect2>
+   </sect1>
+  </chapter>
+  
+  <chapter id=Customizing xreflabel="Customizing DejaGnu">
+    <title>Customizing DejaGnu</title>
+    
+    <para>The site configuration file, <filename>site.exp</filename>,
+    captures configuration-dependent values and propagates them to the
+    DejaGnu test environment using Tcl variables.  This ties the
+    DejaGnu test scripts into the <command>configure</command> and
+    <command>make</command> programs. If this file is setup correctly,
+    it is possible to execute a test suite merely by typing
+    <command>runtest</command>.</para>
+
+    <para>DejaGnu supports two <filename>site.exp</filename>
+    files. The multiple instances of <filename>site.exp</filename> are
+    loaded in a fixed order built into DejaGnu. The first file loaded
+    is the local file <filename>site.exp</filename>, and then the
+    optional global <filename>site.exp</filename> file as
+    pointed to by the <symbol>DEJAGNU</symbol> environment
+    variable.</para>
+
+    <para>There is an optional <emphasis>master</emphasis>
+    <filename>site.exp</filename>, capturing configuration values that
+    apply to DejaGnu across the board, in each configuration-specific
+    subdirectory of the DejaGnu library directory.
+    <command>runtest</command> loads these values first. The master
+    <filename>site.exp</filename> contains the default values for all
+    targets and hosts supported by DejaGnu. This master file is
+    identified by setting the environment variable
+    <symbol>DEJAGNU</symbol> to the name of the file. This is also
+    refered to as the ``global'' config file.</para>
+
+    <para>Any directory containing a configured test suite also has a
+    local <filename>site.exp</filename>, capturing configuration values
+    specific to the tool under test.  Since <command>runtest</command>
+    loads these values last, the individual test configuration can
+    either rely on and use, or override, any of the global values from
+    the global <filename>site.exp</filename> file.</para>
+
+    <para>You can usually generate or update the testsuite's local 
+    <filename>site.exp</filename> by typing <command>make
+    site.exp</command> in the test suite directory, after the test
+    suite is configured.</para>
+
+    <para>You can also have a file in your home directory called
+    <filename>.dejagnurc</filename>. This gets loaded first before the
+    other config files. Usually this is used for personal stuff, like
+    setting the <symbol>all_flag</symbol> so all the output gets
+    printed, or your own verbosity levels. This file is usually
+    restricted to setting command line options.</para>
+
+    <para>You can further override the default values in a
+    user-editable section of any <filename>site.exp</filename>, or by
+    setting variables on the <command>runtest</command> command
+    line.</para>
+
+    <sect1 id=local xreflabel="Local Config File">
+      <title>Local Config File</title>
+    
+      <para>It is usually more convenient to keep these <emphasis>manual
+      overrides</emphasis> in the <filename>site.exp</filename>
+      local to each test directory, rather than in the global
+      <filename>site.exp</filename> in the installed DejaGnu
+      library. This file is mostly for supplying tool specific info
+      that is required by the test suite.</para>
+
+      <para>All local <filename>site.exp</filename> files have
+      two sections, separated by comment text. The first section is
+      the part that is generated by <command>make</command>. It is
+      essentially a collection of Tcl variable definitions based on
+      <filename>Makefile</filename> environment variables. Since they
+      are generated by <command>make</command>, they contain the
+      values as specified by <command>configure</command>.  (You can
+      also customize these values by using the <option>--site</option>
+      option to <command>configure</command>.) In particular, this
+      section contains the <filename>Makefile</filename>
+      variables for host and target configuration data. Do not edit
+      this first section; if you do, your changes are replaced next
+      time you run <command>make</command>.</para>
+
+      <example>
+        <title>The first section starts with</title>
+
+	<programlisting>
+	## these variables are automatically generated by make ##
+	# Do not edit here. If you wish to override these values
+	# add them to the last section
+	</programlisting>
+      </example>
+
+      <para>In the second section, you can override any default values
+      (locally to DejaGnu) for all the variables.  The second section
+      can also contain your preferred defaults for all the command
+      line options to <command>runtest</command>. This allows you to
+      easily customize <command>runtest</command> for your preferences
+      in each configured test-suite tree, so that you need not type
+      options repeatedly on the command line.  (The second section may
+      also be empty, if you do not wish to override any defaults.)</para>
+
+      <example>
+        <title>The first section ends with this line</title>
+
+	<programlisting>
+	## All variables above are generated by configure. Do Not Edit ##
+	</programlisting>
+      </example>
+
+      <para>You can make any changes under this line. If you wish to
+      redefine a variable in the top section, then just put a
+      duplicate value in this second section. Usually the values
+      defined in this config file are related to the configuration of
+      the test run. This is the ideal place to set the variables
+      <symbol>host_triplet</symbol>, <symbol>build_triplet</symbol>,
+      <symbol>target_triplet</symbol>. All other variables are tool
+      dependant. ie for testing a compiler, the value for
+      <symbol>CC</symbol> might be set to a freshly built binary, as
+      opposed to one in the user's path.</para>
+
+      <para>Here's an example local site.exp file, as used for
+      <productname>GCC/G++</productname> testing.</para>
+
+      <example>
+        <title>Local Config File</title>
+
+      <programlisting>  
+      ## these variables are automatically generated by make ##
+      # Do not edit here. If you wish to override these values
+      # add them to the last section
+      set rootme "/build/devo-builds/i586-pc-linux-gnulibc1/gcc"
+      set host_triplet i586-pc-linux-gnulibc1
+      set build_triplet i586-pc-linux-gnulibc1
+      set target_triplet i586-pc-linux-gnulibc1
+      set target_alias i586-pc-linux-gnulibc1
+      set CFLAGS ""
+      set CXXFLAGS "-I/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -I$srcdir/../libg++/src -I$srcdir/../libio -I$srcdir/../libstdc++ -I$srcdir/../libstdc++/stl -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libg++ -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libstdc++"
+      append LDFLAGS " -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../ld"
+      set tmpdir /build/devo-builds/i586-pc-linux-gnulibc1/gcc/testsuite
+      set srcdir "${srcdir}/testsuite"
+      ## All variables above are generated by configure. Do Not Edit ##
+    
+      </programlisting>  
+    </example>
+
+    <para>This file defines the required fields for a local config
+    file, namely the three config triplets, and the srcdir. It also
+    defines several other Tcl variables that are used exclusivly by
+    the GCC test suite. For most test cases, the CXXFLAGS and LDFLAGS
+    are supplied by DejaGnu itself for cross testing, but to test a
+    compiler, GCC needs to manipulate these itself.</para>
+
+    </sect1>
+     <sect1 id=global xreflabel="Global Config File">
+      <title>Global Config File</title>
+    
+      <para>The master config file is where all the target specific
+      config variables get set for a whole site get set. The idea is
+      that for a centralized testing lab where people have to share a
+      target between multiple developers. There are settings for both
+      remote targets and remote hosts.  Here's an example of a Master
+      Config File (also called the Global config file) for a
+      <emphasis>canadian cross</emphasis>. A canadian cross is when
+      you build and test a cross compiler on a machine other than the
+      one it's to be hosted on.</para>
+
+      <para>Here we have the config settings for our California
+      office. Note that all config values are site dependant. Here we
+      have two sets of values that we use for testing m68k-aout cross
+      compilers. As both of these target boards has a different
+      debugging protocol, we test on both of them in sequence.</para>
+
+      <example>
+       <title>Global Config file</title>
+
+      <programlisting>
+
+      # Make sure we look in the right place for the board description files.
+      if ![info exists boards_dir] {
+          set boards_dir {}
+      }
+      lappend boards_dir "/nfs/cygint/s1/cygnus/dejagnu/boards"
+
+      verbose "Global Config File: target_triplet is $target_triplet" 2
+      global target_list
+
+      case "$target_triplet" in {
+          { "native" } {
+              set target_list "unix"
+          }
+          { "sparc64-*elf" } {
+              set target_list "sparc64-sim"
+          }
+          { "mips-*elf" } {
+              set target_list "mips-sim wilma barney"
+          }
+          { "mips-lsi-elf" } {
+              set target_list "mips-lsi-sim{,soft-float,el}"
+          }
+          { "sh-*hms" } {
+              set target_list { "sh-hms-sim" "bloozy" }
+          }
+      }
+      </programlisting>
+    </example>
+
+    <para>In this case, we have support for several cross compilers,
+    that all run on this host. For testing on operating systems that
+    don't support Expect, DejaGnu can be run on the local build
+    machine, and it can connect to the remote host and run all the
+    tests for this cross compiler on that host. All the remote OS
+    requires is a working telnetd.</para>
+
+    <para>As you can see, all one does is set the variable
+    <symbol>target_list</symbol> to the list of targets and options to
+    test. The simple settings, like for
+    <emphasis>sparc64-elf</emphasis> only require setting the name of
+    the single board config file. The <emphasis>mips-elf</emphasis>
+    target is more complicated. Here it sets the list to three target
+    boards. One is the default mips target, and both
+    <emphasis>wilma</emphasis> <emphasis>barney</emphasis> are
+    symbolic names for other mips boards. Symbolic names are covered
+    in the <xref linkend=addboard> chapter. The more complicated
+    example is the one for <emphasis>mips-lsi-elf</emphasis>. This one
+    runs the tests with multiple iterations using all possible
+    combinations of the <option>--soft-float</option> and the
+    <option>--el</option> (little endian) option. Needless to say,
+    this last feature is mostly compiler specific.</para>
+
+    </sect1>
+
+    <sect1 id=boardconfig xreflabel="Board Config File">
+      <title>Board Config File</title>
+   
+      <para>The board config file is where board specfic config data
+      is stored. A board config file contains all the higher-level
+      configuration settings. There is a rough inheritance scheme, where it is
+      possible to base a new board description file on an existing one. There
+      are also collections of custom procedures for common environments. For
+      more information on adding a new board config file, go to the <xref
+      linkend=addboard> chapter. </para>
+
+      <para>An example board config file for a GNU simulator is as
+      follows. <function>set_board_info</function> is a procedure that sets the
+      field name to the specified value. The procedures in square brackets
+      <emphasis>[]</emphasis> are <emphasis>helper procedures</emphasis>. Thes
+      are used to find parts of a tool chain required to build an executable
+      image that may reside in various locations. This is mostly of use for
+      when the startup code, the standard C lobraries, or the tool chain itself
+      is part of your build tree.</para>
+
+      <example>
+        <title>Board Config File</title>
+
+      <programlisting>
+      # This is a list of toolchains that are supported on this board.
+      set_board_info target_install {sparc64-elf}
+
+      # Load the generic configuration for this board. This will define any
+      # routines needed by the tool to communicate with the board.
+      load_generic_config "sim"
+
+      # We need this for find_gcc and *_include_flags/*_link_flags.
+      load_base_board_description "basic-sim"
+
+      # Use long64 by default.
+      process_multilib_options "long64"
+
+      setup_sim sparc64
+
+      # We only support newlib on this target. We assume that all multilib
+      # options have been specified before we get here.
+      set_board_info compiler  "[find_gcc]"
+      set_board_info cflags  "[libgloss_include_flags] [newlib_include_flags]"
+      set_board_info ldflags  "[libgloss_link_flags] [newlib_link_flags]"
+      # No linker script.
+      set_board_info ldscript "";
+
+      # Used by a few gcc.c-torture testcases to delimit how large the
+      # stack can be.
+      set_board_info gcc,stack_size 16384
+      # The simulator doesn't return exit statuses and we need to indicate this
+      # the standard GCC wrapper will work with this target.
+      set_board_info needs_status_wrapper 1
+      # We can't pass arguments to programs.
+      set_board_info noargs 1
+      </programlisting>
+     </example>
+
+     <para>There are five helper procedures used in this example. The first
+     one, <function>find gcc</function> looks for a copy of the GNU compiler in
+     your build tree, or it uses the one in your path. This will also return
+     the proper transformed name for a cross compiler if you whole build tree
+     is configured for one. The next helper procedures are
+     <function>libgloss_include_flags</function> &
+     <function>libgloss_link_flags</function>. These return the proper flags to
+     compiler and link an executable image using <xref
+     linkend=libgloss>, the GNU BSP (Board Support Package). The final
+     procedures are <function>newlib_include_flag</function> &
+     <function>newlib_include_flag</function>. These find the Newlib C
+     library, which is a reentrant standard C library for embedded systems
+     comprising of non GPL'd code.</para>
+
+    </sect1>
+
+    <sect1 id=releng xreflabel="Remote Host Testing">
+      <title>Remote Host Testing</title>
+
+      <note><para>Thanks to Dj Delorie for the original paper that
+      this section is based on.</para></note>
+
+      <para>DejaGnu also supports running the tests on a remote
+      host. To set this up, the remote host needs an ftp server, and a
+      telnet server. Currently foreign operating systems used as
+      remote hosts are VxWorks, VRTX, Dos/Win3.1, MacOS, and
+      win95/win98/NT.</para>
+
+      <para>The recommended source for a win95/win98/NT based ftp
+      server is to get IIS (either IIS 1 or Personal Web Server) from
+      <ulink
+      URL="http://www.microsoft.com">http://www.microsoft.com</ulink>.
+      When you install it, make sure you install the FTP server - it's
+      not selected by default. Go into the IIS manager and change the
+      FTP server so that it does not allow anonymous ftp. Set the home
+      directory to the root directory (i.e. c:\) of a suitable
+      drive. Allow writing via ftp.</para>
+
+      <para>It will create an account like IUSR_FOOBAR where foobar is
+      the name of your machine. Go into the user editor and give that
+      account a password that you don't mind hanging around in the
+      clear (i.e. not the same as your admin or personal
+      passwords). Also, add it to all the various permission groups.</para>
+
+      <para>You'll also need a telnet server. For win95/win98/NT, go
+      to the <ulink URL="http://ataman.com">Ataman</ulink> web site,
+      pick up the Ataman Remote Logon Services for Windows, and
+      install it. You can get started on the eval period anyway. Add
+      IUSR_FOOBAR to the list of allowed users, set the HOME directory
+      to be the same as the FTP default directory. Change the Mode
+      prompt to simple.</para>
+
+      <para>Ok, now you need to pick a directory name to do all the
+      testing in. For the sake of this example, we'll call it piggy
+      (i.e. c:\piggy). Create this directory.</para>
+
+      <para>You'll need a unix machine. Create a directory for the
+      scripts you'll need. For this example, we'll use
+      /usr/local/swamp/testing. You'll need to have a source tree
+      somewhere, say /usr/src/devo. Now, copy some files from
+      releng's area in SV to your machine:</para>
+
+      <example>
+        <title>Remote host setup</title>
+
+      <screen>
+      cd /usr/local/swamp/testing
+      mkdir boards
+      scp darkstar.welcomehome.org:/dejagnu/cst/bin/MkTestDir .
+      scp darkstar.welcomehome.org:/dejagnu/site.exp .
+      scp darkstar.welcomehome.org:/dejagnu/boards/useless98r2.exp boards/foobar.exp
+      export DEJAGNU=/usr/local/swamp/testing/site.exp
+
+      </screen>
+      </example>
+
+      <para>You must edit the boards/foobar.exp file to reflect your
+      machine; change the hostname (foobar.com), username
+      (iusr_foobar), password, and ftp_directory (c:/piggy) to match
+      what you selected.</para>
+
+      <para>Edit the global <filename> site.exp</filename> to reflect your
+      boards directory:</para>
+
+      <example>
+        <title>Add The Board Directory</title>
+
+	<programlisting>
+	lappend boards_dir "/usr/local/swamp/testing/boards"
+	</programlisting>
+	</example>
+
+	<para>Now run MkTestDir, which is in the contrib
+	directory. The first parameter is the toolchain prefix, the
+	second is the location of your devo tree. If you are testing a
+	cross compiler (ex: you have sh-hms-gcc.exe in your PATH on
+	the PC), do something like this:</para>
+
+      <example>
+        <title>Setup Cross Remote Testing</title>
+
+	<programlisting>
+	./MkTestDir sh-hms /usr/dejagnu/src/devo
+	</programlisting>
+	</example>
+
+	<para>If you are testing a native PC compiler (ex: you have
+	gcc.exe in your PATH on the PC), do this:
+
+      <example>
+        <title>Setup Native Remote Testing</title>
+
+	<programlisting>
+	./MkTestDir '' /usr/dejagnu/src/devo
+	</programlisting>
+      </example>
+
+	<para>To test the setup, <command>ftp</command> to your PC
+	using the username (iusr_foobar) and password you selected. CD
+	to the test directory. Upload a file to the PC. Now telnet to
+	your PC using the same username and password. CD to the test
+	directory. Make sure the file is there. Type "set" and/or "gcc
+	-v" (or sh-hms-gcc -v) and make sure the default PATH contains
+	the installation you want to test.</para>
+
+      <example>
+        <title>Run Test Remotely</title>
+
+	<programlisting>
+	cd /usr/local/swamp/testing
+	make  -k -w check RUNTESTFLAGS="--host_board foobar --target_board foobar -v -v" > check.out 2>&1
+	</programlisting>
+	</example>
+
+	<para>To run a specific test, use a command like this (for
+	this example, you'd run this from the gcc directory that
+	MkTestDir created):</para>
+
+      <example>
+        <title>Run a Test Remotely</title>
+
+	<programlisting>
+	make check RUNTESTFLAGS="--host_board sloth --target_board sloth -v compile.exp=921202-1.c"
+	</programlisting>
+      </example>
+
+	<para>Note: if you are testing a cross-compiler, put in the
+	correct target board. You'll also have to download more .exp
+	files and modify them for your local configuration. The -v's
+	are optional.</para>
+
+    </sect1>
+
+    <sect1 id=configfile xreflabel="Config File Values">
+      <title>Config File Values</title>
+    
+      <para>DejaGnu uses a named array in Tcl to hold all the info for
+      each machine. In the case of a canadian cross, this means host
+      information as well as target information. The named array is
+      called <symbol>target_info</symbol>, and it has two indices. The
+      following fields are part of the array.</para>
+
+      <sect1 id=optiondefs xreflabel="Option Variables">
+        <title>Command Line Option Variables</title>
+
+	<para>In the user editable second section of the <xref
+	linkend=personal> you can not only override the configuration
+	variables captured in the first section, but also specify
+	default values for all on the <command>runtest</command>
+	command line options.  Save for <option>--debug</option>,
+	<option>--help</option>, and <option>--version</option>, each 
+	command line option has an associated Tcl variable.  Use the
+	Tcl <command>set</command> command to specify a new default
+	value (as for the configuration variables).  The following
+	table describes the correspondence between command line
+	options and variables you can set in
+	<filename>site.exp</filename>.  <xref linkend=invoking>, for
+	explanations of the command-line options.</para>
+
+	<para><table frame=all rowsep=0 colsep=0>
+	  <title>Tcl Variables For Command Line Options</title>
+
+	  <tgroup cols=3 align="char" rowsep=1 colsep=0>
+	  <thead><row>
+	    <entry>runtest</entry><entry>Tcl</entry>
+	    <entry>option</entry><entry>variable</entry><entry>description</entry>
+	  </row></thead>
+	  <tbody>
+
+	  <row>
+	    <entry>--all</entry>
+	    <entry>all_flag</entry>
+	    <entry>display all test results if set</entry>
+	  </row>
+
+	  <row>
+	    <entry>--baud</entry>
+	    <entry>baud</entry>
+	    <entry>set the default baud rate to something other than
+	    9600.</entry>
+	  </row>
+
+	  <row>
+	    <entry>--connect</entry>
+	    <entry>connectmode</entry>
+	    <entry><command>rlogin</command>,
+	    <command>telnet</command>, <command>rsh</command>,
+	    <command>kermit</command>, <command>tip</command>, or
+	    <command>mondfe</command></entry>
+	  </row>
+
+	  <row>
+            <entry>--outdir</entry>
+	    <entry>outdir</entry>
+	    <entry>directory for <filename>tool.sum</filename> and
+	    <filename>tool.log.</filename></entry>
+	  </row>
+
+	  <row>
+	    <entry>--objdir</entry>
+	    <entry>objdir</entry>
+	    <entry>directory for pre-compiled binaries</entry>
+	  </row>
+
+	  <row>
+	    <entry>--reboot</entry>
+	    <entry>reboot</entry>
+	    <entry>reboot the target if set to
+	    <emphasis>"1"</emphasis>; do not reboot if set to
+	    <emphasis>"0"</emphasis> (the default).</entry>
+	  </row>
+
+	  <row>
+	    <entry>--srcdir</entry>
+	    <entry>srcdir</entry>
+	    <entry>directory of test subdirectories</entry>
+	  </row>
+
+	  <row>
+	    <entry>--strace</entry>
+	    <entry>tracelevel</entry>
+	    <entry>a number: Tcl trace depth</entry>
+	  </row>
+
+	  <row>
+	    <entry>--tool</entry>
+	    <entry>tool</entry>
+	    <entry>name of tool to test; identifies init, test subdir</entry>
+	  </row>
+
+	  <row>
+	    <entry>--verbose</entry>
+	    <entry>verbose</entry>
+	    <entry>verbosity level.  As option, use multiple times; as
+	    variable, set a number, 0 or greater.</entry>
+	  </row>
+
+	  <row>
+	    <entry>--target</entry>
+	    <entry>target_triplet</entry>
+	    <entry>The canonical configuration string for the target.</entry>
+	  </row>
+
+	  <row>
+	    <entry>--host</entry>
+	    <entry>host_triplet</entry>
+	    <entry>The canonical configuration string for the host.</entry>
+	  </row>
+
+	  <row>
+	    <entry>--build</entry>
+	    <entry>build_triplet</entry>
+	    <entry>The canonical configuration string for the build
+	    host.</entry>
+	  </row>
+
+	  </tbody>
+	  </tgroup>
+	  </table>
+	</para>
+
+    </sect1>
+
+    <sect1 id=personal xreflabel="Personal Config File">
+      <title>Personal Config File</title>
+    
+      <para>The personal config file is used to customize
+      <command>runtest's</command> behaviour for each person. It's
+      typically used to set the user prefered setting for verbosity,
+      and any experimental Tcl procedures. My personal
+      <filename>~/.dejagnurc</filename> file looks like:</para>
+
+      <example>
+        <title>Personal Config File</title>
+
+	<programlisting>
+	set all_flag 1
+	set RLOGIN /usr/ucb/rlogin
+	set RSH /usr/local/sbin/ssh
+	</programlisting>
+      </example>
+
+      <para>Here I set <symbol>all_flag</symbol> so I see all the test
+      cases that PASS along with the ones that FAIL. I also set
+      <symbol>RLOGIN</symbol> to the BSD version. I have
+      <productname>Kerberos</productname> installed, and when I rlogin
+      to a target board, it usually isn't supported. So I use the non
+      secure version rather than the default that's in my path. I also
+      set <symbol>RSH</symbol> to the <productname>SSH</productname>
+      secure shell, as rsh is mostly used to test unix
+      machines within a local network here.</para>
+
+    </sect1>
+
+  </chapter>
+  
+  <chapter id=Extending xreflabel="Extending DejaGnu">
+    <title>Extending DejaGnu</title>
+    
+    <sect1 id=addsuite  xreflabel="Adding a new Test Suite">
+      <title>Adding A New Test Suite</title>
+    
+      <para>The testsuite for a new tool should always be located in that tools
+      source directory. DejaGnu require the directory be named
+      <filename>testsuite</filename>. Under this directory, the test cases go
+      in a subdirectory whose name begins with the tool name. For example, for
+      a tool named <emphasis>flubber</emphasis>, each subdirectory containing
+      testsuites must start with <emphasis>"flubber."</emphasis>.</para>
+
+    </sect1>
+
+    <sect1 id=addtool xreflabel="Adding A New Tool">
+      <title>Adding A New Tool</title>
+    
+      <para>In general, the best way to learn how to write (code or even prose)
+      is to read something similar.  This principle applies to test cases and
+      to test suites.  Unfortunately, well-established test suites have a way
+      of developing their own conventions: as test writers become more
+      experienced with DejaGnu and with Tcl, they accumulate more utilities,
+      and take advantage of more and more features of
+      <productname>Expect</productname> and <productname>Tcl</productname> in
+      general.</para>
+
+      <para>Inspecting such established test suites may make the prospect of
+      creating an entirely new test suite appear overwhelming.  Nevertheless,
+      it is quite straightforward to get a new test suite going.</para>
+
+      <para>There is one test suite that is guaranteed not to grow more
+      elaborate over time: both it and the tool it tests were created expressly
+      to illustrate what it takes to get started with DejaGnu.  The
+      <filename>example/</filename> directory of the DejaGnu distribution
+      contains both an interactive tool called <command>calc</command>, and a
+      test suite for it.  Reading this test suite, and experimenting with it,
+      is a good way to supplement the information in this section.  (Thanks to
+      Robert Lupton for creating calc and its test suite---and also the first
+      version of this section of the manual!)</para>
+
+      <para>To help orient you further in this task, here is an outline of the
+      steps to begin building a test suite for a program example.</para>
+
+      <itemizedlist mark=bullet>
+      
+      <listitem><para>Create or select a directory to contain your new
+      collection of tests. Change into that directory (shown here as
+      <filename>testsuite</filename>):</para>
+              
+      <para>Create a <filename>configure.in</filename> file in this directory,
+      to control configuration-dependent choices for your tests.  So far as
+      DejaGnu is concerned, the important thing is to set a value for the
+      variable <symbol>target_abbrev</symbol>; this value is the link to the
+      init file you will write soon.  (For simplicity, we assume the
+      environment is Unix, and use <emphasis>unix</emphasis> as the
+      value.)</para>
+
+      <para>What else is needed in <filename>configure.in</filename> depends on
+      the requirements of your tool, your intended test environments, and which
+      configure system you use.  This example is a minimal configure.in for use
+      with <productname>GNU Autoconf</productname>. </para></listitem>
+
+      <listitem><para>Create <filename>Makefile.in</filename> (if you are using
+      Autoconf), or <filename>Makefile.am</filename>(if you are using
+      Automake), the source file used by configure to build your
+      <filename>Makefile</filename>. If you are using GNU Automake.just add the
+      keyword <emphasis>dejagnu</emphasis> to the
+      <emphasis>AUTOMAKE_OPTIONS</emphasis> variable in your
+      <filename>Makefile.am</filename> file. This will add all the Makefile
+      support needed to run DejaGnu, and support the <xref linkend=makecheck>
+      target.</para>
+
+      <para>You also need to include two targets important to DejaGnu:
+      <emphasis>check</emphasis>, to run the tests, and
+      <emphasis>site.exp</emphasis>, to set up the Tcl copies of
+      configuration-dependent values. This is called the <xref linkend=local>
+      The check target must run the <command>runtest</command> program to
+      execute the tests.</para>
+
+      <para>The <filename>site.exp</filename> target should usually set up
+      (among other things) the $tool variable for the name of your program. If
+      the local site.exp file is setup correctly, it is possible to execute the
+      tests by merely typing <command>runtest</command> on the command
+      line.</para>
+
+      <example>
+        <title>Sample Makefile.in Fragment</title>
+
+	<programlisting>
+	# Look for a local version of DejaGnu, otherwise use one in the path
+	RUNTEST = `if test -f $(top_srcdir)/../dejagnu/runtest; then \
+	      echo $(top_srcdir) ../dejagnu/runtest; \
+	    else \
+	       echo runtest; \
+	     fi`
+
+	# The flags to pass to runtest
+	RUNTESTFLAGS =
+
+	# Execute the tests 
+	check: site.exp all
+        $(RUNTEST) $(RUNTESTFLAGS) \
+            --tool <symbol>${example}</symbol> --srcdir $(srcdir) 
+
+	# Make the local config file
+	site.exp: ./config.status Makefile
+	    @echo "Making a new config file..."
+            -@rm -f ./tmp?
+            @touch site.exp
+
+            -@mv site.exp site.bak
+            @echo "## these variables are automatically\
+ generated by make ##" > ./tmp0
+	    @echo "# Do not edit here. If you wish to\
+ override these values" >> ./tmp0
+            @echo "# add them to the last section" >> ./tmp0
+            @echo "set host_os ${host_os}" >> ./tmp0
+            @echo "set host_alias ${host_alias}" >> ./tmp0
+            @echo "set host_cpu ${host_cpu}" >> ./tmp0
+            @echo "set host_vendor ${host_vendor}" >> ./tmp0
+            @echo "set target_os ${target_os}" >> ./tmp0
+            @echo "set target_alias ${target_alias}" >> ./tmp0
+            @echo "set target_cpu ${target_cpu}" >> ./tmp0
+            @echo "set target_vendor ${target_vendor}" >> ./tmp0
+            @echo "set host_triplet ${host_canonical}" >> ./tmp0
+            @echo "set target_triplet ${target_canonical}">>./tmp0
+            @echo "set tool binutils" >> ./tmp0
+            @echo "set srcdir ${srcdir}" >> ./tmp0
+            @echo "set objdir `pwd`" >> ./tmp0
+            @echo "set <symbol>${examplename}</symbol> <symbol>${example}</symbol>" >> ./tmp0
+            @echo "## All variables above are generated by\
+ configure. Do Not Edit ##" >> ./tmp0
+            @cat ./tmp0 > site.exp
+            @sed < site.bak \
+               -e '1,/^## All variables above are.*##/ d' \
+               >> site.exp
+            -@rm -f ./tmp?
+
+	    </programlisting>
+	    </example>
+	  </listitem>
+	  
+	  <listitem><para>Create a directory (in <filename>testsuite</filename>)
+	  called <filename>config</filename>. Make a <emphasis>Tool Init
+	  File</emphasis> in this directory. Its name must start with the
+	  <symbol>target_abbrev</symbol> value, or be named
+	  <filename>default.exp</filename> so call it
+	  <filename>config/unix.exp</filename> for our Unix based example. This
+	  is the file that contains the target-dependent procedures.
+	  Fortunately, on Unix, most of them do not have to do very much in
+	  order for <command>runtest</command> to run.</para>
+
+	  <para>If the program being tested is not interactive, you can get
+	  away with this minimal <filename>unix.exp</filename> to begin
+	  with:</para>
+
+	  <example>
+	    <title>Simple Batch Program Tool Init File</title>
+	  
+	  <programlisting>
+	  
+	  proc foo_exit {} {}
+	  proc foo_version {} {}
+
+	  </programlisting>
+	  </example>
+
+	  <para>If the program being tested is interactive, however, you might
+	  as well define a <emphasis>start</emphasis> routine and invoke it by
+	  using an init file like this:</para>
+
+	  <example>
+	    <title>Simple Interactive Program Tool Init File</title>
+
+	  <programlisting>
+	
+	  proc foo_exit {} {}
+	  proc foo_version {} {}
+
+	  proc foo_start {} {
+	    global ${examplename}
+	    spawn ${examplename}
+	    expect {
+	        -re "" {}
+	    }
+	  }
+
+	  # Start the program running we want to test
+	  foo_start
+
+	  </programlisting>
+	  </example>
+	  </listitem>
+
+	  <listitem><para>Create a directory whose name begins with your tool's
+	  name, to contain tests. For example, if your tool's name is
+	  <emphasis>gcc</emphasis>, then the directories all need to start with
+	  <emphasis>"gcc."</emphasis>.</para></listitem>
+
+	  <listitem><para>Create a sample test file. Its name must end with
+	  <filename>.exp</filename>. You can use
+	  <filename>first-try.exp</filename>. To begin with, just write there a
+	  line of Tcl code to issue a message.</para>
+
+	  <example>
+	    <title>Testing A New Tool Config</title>
+
+	  <programlisting>
+
+	  send_user "Testing: one, two...\n"
+
+	  </programlisting>
+	  </example>
+  	  </listitem>
+
+	  <listitem><para>Back in the <filename>testsuite</filename> (top
+	  level) directory, run <command>configure</command>. Typically you do
+	  this while in the build directory. You may have to specify more of a
+	  path, if a suitable configure is not available in your execution
+	  path.</para></listitem>
+
+	  <listitem><para>e now ready to triumphantly type <command>make
+	  check</command> or <command>runtest</command>.  You should see
+	  something like this:</para>
+
+	  <example>
+	    <title>Example Test Case Run</title>
+
+	  <screen>
+	  Test Run By rhl on Fri Jan 29 16:25:44 EST 1993
+
+                === example tests ===
+
+	  Running ./example.0/first-try.exp ...
+	  Testing: one, two...
+
+                === example Summary ===
+
+	 </screen>
+	 </example>
+
+	 <para>There is no output in the summary, because so far the example
+	 does not call any of the procedures that establish a test
+	 outcome.</para></listitem>
+
+	 <listitem><para>Write some real tests. For an interactive tool, you
+	 should probably write a real exit routine in fairly short order. In
+	 any case, you should also write a real version routine
+	 soon. </para></listitem>
+
+    </itemizedlist>
+
+    </sect1>
+
+    <sect1 id=addtarget xreflabel="Adding A New Target">
+      <title>Adding A New Target</title>
+    
+      <para>DejaGnu has some additional requirements for target support, beyond
+      the general-purpose provisions of configure. DejaGnu must actively
+      communicate with the target, rather than simply generating or managing
+      code for the target architecture.  Therefore, each tool requires an
+      initialization module for each target.  For new targets, you must supply
+      a few Tcl procedures to adapt DejaGnu to the target.  This permits
+      DejaGnu itself to remain target independent.</para>
+
+      <para>Usually the best way to write a new initialization module is to
+      edit an existing initialization module; some trial and error will be
+      required. If necessary, you can use the @samp{--debug} option to see what
+      is really going on.</para>
+
+      <para>When you code an initialization module, be generous in printing
+      information controlled by the <function>verbose</function>
+      procedure.</para>
+
+      <para>For cross targets, most of the work is in getting the
+      communications right. Communications code (for several situations
+      involving IP networks or serial lines) is available in a DejaGnu library
+      file.</para>
+
+      <para>If you suspect a communication problem, try running the connection
+      interactively from <productname>Expect</productname>.  (There are three
+      ways of running <productname>Expect</productname> as an interactive
+      interpreter.  You can run <productname>Expect</productname> with no
+      arguments, and control it completely interactively; or you can use
+      <command>expect -i</command> together with other command-line options and
+      arguments; or you can run the command <command>interpreter</command> from
+      any <productname>Expect</productname> procedure.  Use
+      <command>return</command> to get back to the calling procedure (if any),
+      or <command>return -tcl</command> to make the calling procedure itself
+      return to its caller; use <command>exi</command>t or end-of-file to leave
+      Expect altogether.)  Run the program whose name is recorded in
+      <symbol>$connectmode</symbol>, with the arguments in
+      <symbol>$targetname</symbol>, to establish a connection.  You should at
+      least be able to get a prompt from any target that is physically
+      connected.</para>
+
+    </sect1>
+
+    <sect1 id=addboard xreflabel="Adding A New Board">
+      <title>Adding A New Board</title>
+    
+      <para>Adding a new board consists of creating a new board config
+      file. Examples are in
+      <filename>dejagnu/baseboards</filename>. Usually to make a new
+      board file, it's easiest to copy an existing one. It is also
+      possible to have your file be based on a
+      <emphasis>baseboard</emphasis> file with only one or two
+      changes needed. Typically, this can be as simple as just
+      changing the linker script. Once the new baseboard file is done,
+      add it to the <symbol>boards_DATA</symbol> list in the
+      <filename>dejagnu/baseboards/Makefile.am</filename>, and regenerate the
+      Makefile.in using automake. Then just rebuild and install DejaGnu. You
+      can test it by:</para>
+
+      <para>There is a crude inheritance scheme going on with board files, so
+      you can include one board file into another, The two main procedures used
+      to do this are <function>load_generic_config</function> and
+      <function>load_base_board_description</function>. The generic config file
+      contains other procedures used for a certain class of target. The
+      board description file is where the board specfic settings go. Commonly
+      there are similar target environments with just different
+      processors.</para> 
+
+      <example>
+      <title>Testing a New Board Config File</title>
+
+      <screen>
+      make check RUNTESTFLAGS="--target_board=<emphasis>newboardfile</emphasis>".
+      </screen>
+      </example>
+
+      <para>Here's an example of a board config file. There are
+      several <emphasis>helper procedures</emphasis> used in this
+      example. A helper procedure is one that look for a tool of files
+      in commonly installed locations. These are mostly used when
+      testing in the build tree, because the executables to be tested
+      are in the same tree as the new dejagnu files. The helper
+      procedures are the ones in square braces
+      <emphasis>[]</emphasis>, which is the Tcl execution characters.</para> 
+
+      <example>
+      <title>Example Board Config File</title>
+
+      <programlisting>
+
+      # Load the generic configuration for this board. This will define a basic
+      # set of routines needed by the tool to communicate with the board.
+      load_generic_config "sim"
+
+      # basic-sim.exp is a basic description for the standard Cygnus simulator.
+      load_base_board_description "basic-sim"
+
+      # The compiler used to build for this board. This has *nothing* to do
+      # with what compiler is tested if we're testing gcc.
+      set_board_info compiler "[find_gcc]"
+
+      # We only support newlib on this target.
+      # However, we include libgloss so we can find the linker scripts.
+      set_board_info cflags "[newlib_include_flags] [libgloss_include_flags]"
+      set_board_info ldflags "[newlib_link_flags]"
+
+      # No linker script for this board.
+      set_board_info ldscript "-Tsim.ld";
+
+      # The simulator doesn't return exit statuses and we need to indicate this.
+      set_board_info needs_status_wrapper 1
+
+      # Can't pass arguments to this target.
+      set_board_info noargs 1
+
+      # No signals.
+      set_board_info gdb,nosignals 1
+
+      # And it can't call functions.
+      set_board_info gdb,cannot_call_functions 1
+
+      </programlisting>
+      </example>
+
+    </sect1>
+
+    <sect1 id=boarddefs xreflabel="Board File Values">
+      <title>Board Config File Values</title>
+
+      <para>These fields are all in the <symbol>board_info</symbol> These are
+      all set by using the <function>set_board_info</function> procedure. The
+      parameters are the field name, followed by the value to set the field
+      to.</para>
+
+  	 <para><table frame=all rowsep=0 colsep=0>
+	  <title>Common Board Info Fields</title>
+
+	  <tgroup cols=3 align="char" rowsep=1 colsep=0>
+	  <thead><row>
+	    <entry>Field</entry>
+	    <entry>Sample Value</entry>
+	    <entry>Description</entry>
+	  </row></thead>
+	  <tbody>
+
+	  <row>
+	    <entry>compiler</entry>
+	    <entry>"[find_gcc]"</entry>
+	    <entry>The path to the compiler to use.</entry>
+	  </row>
+
+	  <row>
+	    <entry>cflags</entry>
+	    <entry>"-mca"</entry>
+	    <entry>Compilation flags for the compiler.</entry>
+	  </row>
+
+	  <row>
+	    <entry>ldflags</entry>
+	    <entry>"[libgloss_link_flags] [newlib_link_flags]"</entry>
+	    <entry>Linking flags for the compiler.</entry>
+	  </row>
+
+	  <row>
+	    <entry>ldscript</entry>
+	    <entry>"-Wl,-Tidt.ld"</entry>
+	    <entry>The linker script to use when cross compiling.</entry>
+	  </row>
+
+	  <row>
+	    <entry>libs</entry>
+	    <entry>"-lgcc"</entry>
+	    <entry>Any additional libraries to link in.</entry>
+	  </row>
+
+	  <row>
+	    <entry>shell_prompt</entry>
+	    <entry>"cygmon>"</entry>
+	    <entry>The command prompt of the remote shell.</entry>
+	  </row>
+
+	  <row>
+	    <entry>hex_startaddr</entry>
+	    <entry>"0xa0020000"</entry>
+	    <entry>The Starting address as a string.</entry>
+	  </row>
+
+	  <row>
+	    <entry>start_addr</entry>
+	    <entry>0xa0008000</entry>
+	    <entry>The starting address as a value.</entry>
+	  </row>
+
+	  <row>
+	    <entry>startaddr</entry>
+	    <entry>"a0020000"</entry>
+	    <entry></entry>
+	  </row>
+
+	  <row>
+	    <entry>exit_statuses_bad</entry>
+	    <entry>1</entry>
+	    <entry>Whether there is an accurate exit status.</entry>
+	  </row>
+
+	  <row>
+	    <entry>reboot_delay</entry>
+	    <entry>10</entry>
+	    <entry>The delay between power off and power on.</entry>
+	  </row>
+
+	  <row>
+	    <entry>unreliable</entry>
+	    <entry>1</entry>
+	    <entry>Whether communication with the board is unreliable.</entry>
+	  </row>
+
+	  <row>
+	    <entry>sim</entry>
+	    <entry>[find_sim]</entry>
+	    <entry>The path to the simulator to use.</entry>
+	  </row>
+
+	  <row>
+	    <entry>objcopy</entry>
+	    <entry>$tempfil</entry>
+	    <entry>The path to the <command>objcopy</command> program.</entry>
+	  </row>
+
+	  <row>
+	    <entry>support_libs</entry>
+	    <entry>"${prefix_dir}/i386-coff/"</entry>
+	    <entry>Support libraries needed for cross compiling.</entry>
+	  </row>
+
+	  <row>
+	    <entry>addl_link_flags</entry>
+	    <entry>"-N"</entry>
+	    <entry>Additional link flags, rarely used.</entry>
+	  </row>
+
+	  </tbody>
+	  </tgroup>
+	  </table>
+	</para>
+
+	 <para>These fields are used by the GCC and GDB tests, and are mostly
+	 only useful to somewhat trying to debug a new board file for one of
+	 these tools. Many of these are used only by a few testcases, and their
+	 purpose is esoteric. These are listed with sample values as a guide to
+	 better guessing if you need to change any of these.</para>
+
+  	 <para><table frame=all rowsep=0 colsep=0>
+	  <title>Board Info Fields For GCC & GDB</title>
+
+	  <tgroup cols=3 align="char" rowsep=1 colsep=0>
+	  <thead><row>
+	    <entry>Field</entry>
+	    <entry>Sample Value</entry>
+	    <entry>Description</entry>
+	  </row></thead>
+	  <tbody>
+
+	  <row>
+	    <entry>strip</entry>
+	    <entry>$tempfile</entry>
+	    <entry>Strip the executable of symbols.</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_load_offset</entry>
+	    <entry>"0x40050000"</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_protocol</entry>
+	    <entry>"remote"</entry>
+	    <entry>The GDB debugging protocol to use.</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_sect_offset</entry>
+	    <entry>"0x41000000";</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_stub_ldscript</entry>
+	    <entry>"-Wl,-Teva-stub.ld"</entry>
+	    <entry>The linker script to use with a GDB stub.</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_init_command</entry>
+	    <entry>"set mipsfpu none"</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb,cannot_call_functions</entry>
+	    <entry>1</entry>
+	    <entry>Whether GDB can call functions on the target,</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb,noargs</entry>
+	    <entry>1</entry>
+	    <entry>Whether the target can take command line arguments.</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb,nosignals</entry>
+	    <entry>1</entry>
+	    <entry>Whether there are signals on the target.</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb,short_int</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb,start_symbol</entry>
+	    <entry>"_start";</entry>
+	    <entry>The starting symbol in the executable.</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb,target_sim_options</entry>
+	    <entry>"-sparclite"</entry>
+	    <entry>Special options to pass to the simulator.</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb,timeout</entry>
+	    <entry>540</entry>
+	    <entry>Timeout value to use for remote communication.</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_init_command</entry>
+	    <entry>"print/x \$fsr = 0x0"</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_load_offset</entry>
+	    <entry>"0x12020000"</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_opts</entry>
+	    <entry>"--command gdbinit"</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_prompt</entry>
+	    <entry>"\\(gdb960\\)"</entry>
+	    <entry>The prompt GDB is using.</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_run_command</entry>
+	    <entry>"jump start"</entry>
+	  </row>
+
+	  <row>
+	    <entry>gdb_stub_offset</entry>
+	    <entry>"0x12010000"</entry>
+	  </row>
+
+	  <row>
+	    <entry>use_gdb_stub</entry>
+	    <entry>1</entry>
+	    <entry>Whether to use a GDB stub.</entry>
+	  </row>
+
+	  <row>
+	    <entry>use_vma_offset</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>wrap_m68k_aout</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>gcc,no_label_values</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>gcc,no_trampolines</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>gcc,no_varargs</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>gcc,stack_size</entry>
+	    <entry>16384</entry>
+	    <entry>Stack size to use with some GCC testcases.</entry>
+	  </row>
+
+	  <row>
+	    <entry>ieee_multilib_flags</entry>
+	    <entry>"-mieee";</entry>
+	  </row>
+
+	  <row>
+	    <entry>is_simulator</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>needs_status_wrapper</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>no_double</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>no_long_long</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>noargs</entry>
+	    <entry>1</entry>
+	  </row>
+
+	  <row>
+	    <entry>nullstone,lib</entry>
+	    <entry>"mips-clock.c"</entry>
+	  </row>
+
+	  <row>
+	    <entry>nullstone,ticks_per_sec</entry>
+	    <entry>3782018</entry>
+	  </row>
+
+	  <row>
+	    <entry>sys_speed_value</entry>
+	    <entry>200</entry>
+	  </row>
+
+	  <row>
+	    <entry>target_install</entry>
+	    <entry>{sh-hms}</entry>
+	  </row>
+
+	  </tbody>
+	  </tgroup>
+	  </table>
+	</para>
+
+    </sect1>
+
+    <sect1 id=writing xreflabel="Writing A Test Case">
+      <title>Writing A Test Case</title>
+    
+      <para>The easiest way to prepare a new test case is to base it
+      on an existing one for a similar situation.  There are two major
+      categories of tests: batch or interactive.  Batch oriented tests
+      are usually easier to write.</para>
+
+      <para>The GCC tests are a good example of batch oriented tests.
+      All GCC tests consist primarily of a call to a single common
+      procedure, Since all the tests either have no output, or only
+      have a few warning messages when successfully compiled.  Any
+      non-warning output is a test failure.  All the C code needed is
+      kept in the test directory.  The test driver, written in Tcl,
+      need only get a listing of all the C files in the directory, and
+      compile them all using a generic procedure. This procedure and a
+      few others supporting for these tests are kept in the library
+      module <filename>lib/c-torture.exp</filename> in the GCC test
+      suite. Most tests of this kind use very few
+      <productname>expect</productname> features, and are coded almost
+      purely in Tcl.</para>
+
+      <para>Writing the complete suite of C tests, then, consisted of
+      these steps:</para>
+
+      <itemizedlist mark=bullet>
+      <listitem><para>Copying all the C code into the test directory.
+      These tests were based on the C-torture test created by Torbjorn
+      Granlund (on behalf of the Free Software Foundation) for GCC
+      development.</para></listitem>
+
+      <listitem><para>Writing (and debugging) the generic Tcl procedures for
+      compilation.</para></listitem>
+
+      <listitem><para>Writing the simple test driver: its main task is to
+      search the directory (using the Tcl procedure
+      <emphasis>glob</emphasis> for filename expansion with wildcards)
+      and call a Tcl procedure with each filename.  It also checks for
+      a few errors from the testing procedure.</para></listitem>
+      </itemizedlist>
+
+      <para>Testing interactive programs is intrinsically more
+      complex.  Tests for most interactive programs require some trial
+      and error before they are complete.</para>
+
+      <para>However, some interactive programs can be tested in a
+      simple fashion reminiscent of batch tests.  For example, prior
+      to the creation of DejaGnu, the GDB distribution already
+      included a wide-ranging testing procedure.  This procedure was
+      very robust, and had already undergone much more debugging and
+      error checking than many recent DejaGnu test cases.
+      Accordingly, the best approach was simply to encapsulate the
+      existing GDB tests, for reporting purposes. Thereafter, new GDB
+      tests built up a family of Tcl procedures specialized for GDB
+      testing.</para>
+
+    </sect1>
+
+    <sect1 id=debugging xreflabel="Debugging A Test Case">
+      <title>Debugging A Test Case</title>
+    
+      <para>These are the kinds of debugging information available
+      from DejaGnu:</para>
+
+      <itemizedlist mark=bullet>
+
+      <listitem><para>Output controlled by test scripts themselves,
+      explicitly allowed for by the test author.  This kind of
+      debugging output appears in the detailed output recorded in the
+      DejaGnu log file.  To do the same for new tests, use the
+      <command>verbose</command> procedure (which in turn uses the
+      variable also called <emphasis>verbose</emphasis>) to control
+      how much output to generate.  This will make it easier for other
+      people running the test to debug it if necessary.  Whenever
+      possible, if <emphasis>$verbose</emphasis> is
+      <emphasis>0</emphasis>, there should be no output other than the
+      output from <emphasis>pass</emphasis>,
+      <emphasis>fail</emphasis>, <emphasis>error</emphasis>, and
+      <emphasis>warning</emphasis>.  Then, to whatever extent is
+      appropriate for the particular test, allow successively higher
+      values of <emphasis>$verbose</emphasis> to generate more
+      information.  Be kind to other programmers who use your tests:
+      provide for a lot of debugging information.</para>
+
+      <listitem><para>Output from the internal debugging functions of
+      Tcl and <productname>Expect</productname>. There is a command
+      line options for each; both forms of debugging output are
+      recorded in the file <filename>dbg.log</filename> in the current
+      directory.</para> 
+
+      <para>Use <option>--debug</option> for information from the
+       expect level; it generates displays of the expect attempts to
+       match the tool output with the patterns specified. This output
+       can be very helpful while developing test scripts, since it
+       shows precisely the characters received.  Iterating between the
+       latest attempt at a new test script and the corresponding
+       <filename>dbg.log</filename> can allow you to create the final
+       patterns by ``cut and paste''.  This is sometimes the best way
+       to write a test case.</para>
+
+       <listitem><para>Use <option>--strace</option> to see more
+       detail at the Tcl level; this shows how Tcl procedure
+       definitions expand, as they execute. The associated number
+       controls the depth of definitions expanded.</para></listitem>
+
+       <listitem><para>Finally, if the value of
+       <emphasis>verbose</emphasis> is 3 or greater,DejaGnu turns on
+       the expect command <command>log_user</command>.  This command
+       prints all expect actions to the expect standard output, to the
+       detailed log file, and (if <option>--debug</option> is on) to
+       <filename>dbg.log</filename>.</para>
+       </itemizedlist>
+
+    </sect1>
+
+    <sect1 id=adding xreflabel="Adding A Test Case To A Test Suite">
+      <title>Adding A Test Case To A Test Suite.</title>
+    
+      <para>There are two slightly different ways to add a test
+      case. One is to add the test case to an existing directory. The
+      other is to create a new directory to hold your test. The
+      existing test directories represent several styles of testing,
+      all of which are slightly different; examine the directories for
+      the tool of interest to see which (if any) is most suitable.</para>
+
+      <para>Adding a GCC test can be very simple: just add the C code
+      to any directory beginning with <filename>gcc</filename>. and it
+      runs on the next <programlisting>runtest --tool
+      gcc</programlisting>.</para>
+
+      <para>To add a test to GDB, first add any source code you will
+      need to the test directory. Then you can either create a new
+      expect file, or add your test to an existing one (any
+      file with a <emphasis>.exp</emphasis> suffix).  Creating a new
+      .exp file is probably a better idea if the test is significantly
+      different from existing tests. Adding it as a separate file also
+      makes upgrading easier. If the C code has to be already compiled
+      before the test will run, then you'll have to add it to the
+      <filename>Makefile.in</filename> file for that test directory,
+      then run <command>configure</command> and
+      <command>make</command>.</para>
+
+      <para>Adding a test by creating a new directory is very
+      similar:</para>
+
+      <itemizedlist mark=bullet>
+
+      <listitem><para>Create the new directory. All subdirectory names
+      begin with the name of the tool to test; e.g. G++ tests might be
+      in a directory called <filename>g++.other</filename>. There can
+      be multiple test directories that start with the same tool name
+      (such as <emphasis>g++</emphasis>).</para></listitem>
+
+      <listitem><para>Add the new directory name to the
+      <symbol>configdirs</symbol> definition in the
+      <filename>configure.in</filename> file for the test suite
+      directory. This way when <command>make</command> and
+      <command>configure</command> next run, they include the new
+      directory.</para></listitem>
+
+      <listitem><para>Add the new test case to the directory, as
+      above. </para>
+
+      <listitem><para>To add support in the new directory for
+      configure and make, you must also create a
+      <filename>Makefile.in</filename> and a
+      <filename>configure.in</filename>.</para></listitem> 
+      </itemizedlist>
+
+    </sect1>
+
+    <sect1 id=hints xreflabel="Hints On Writing A Test Case">
+      <title>Hints On Writing A Test Case</title>
+    
+      <para>It is safest to write patterns that match all the output
+      generated by the tested program; this is called closure.
+      If a pattern does not match the entire output, any output that
+      remains will be examined by the next <command>expect</command>
+      command. In this situation, the precise boundary that determines
+      which <command>expect</command> command sees what is very
+      sensitive to timing between the Expect task and the task running
+      the tested tool.  As a result, the test may sometimes appear to
+      work, but is likely to have unpredictable results. (This problem
+      is particularly likely for interactive tools, but can also
+      affect batch tools---especially for tests that take a long time
+      to finish.) The best way to ensure closure is to use the
+      <option>-re</option> option for the <command>expect</command>
+      command to write the pattern as a full regular expressions; then
+      you can match the end of output using a <emphasis>$</emphasis>.
+      It is also a good idea to write patterns that match all
+      available output by using <emphasis>.*\</emphasis> after the
+      text of interest; this will also match any intervening blank
+      lines.  Sometimes an alternative is to match end of line using
+      <emphasis>\r</emphasis> or <emphasis>\n</emphasis>, but this is
+      usually too dependent on terminal settings.</para>
+
+      <para>Always escape punctuation, such as <emphasis>(</emphasis>
+      or <emphasis>"</emphasis>, in your patterns; for example, write
+      <emphasis>\(</emphasis>.  If you forget to escape punctuation,
+      you will usually see an error message like <programlisting>extra
+      characters after close-quote.</programlisting></para>
+
+      <para>If you have trouble understanding why a pattern does not
+      match the program output, try using the <option>--debug</option>
+      option to <command>runtest</command>, and examine the debug log
+      carefully.</para>
+
+      <para>Be careful not to neglect output generated by setup rather
+      than by the interesting parts of a test case.  For example,
+      while testing GDB, I issue a send <emphasis>set height
+      0\n</emphasis> command.  The purpose is simply to make sure GDB
+      never calls a paging program.  The <emphasis>set
+      height</emphasis> command in GDB does not generate any
+      output; but running any command makes GDB issue a new
+      <emphasis>(gdb) </emphasis> prompt.  If there were no
+      <command>expect</command> command to match this prompt, the
+      output <emphasis>(gdb) </emphasis> begins the text seen by the
+      next <command>expect</command> command---which might make that
+      pattern fail to match.</para>
+
+      <para>To preserve basic sanity, I also recommended that no test
+      ever pass if there was any kind of problem in the test case.  To
+      take an extreme case, tests that pass even when the tool will
+      not spawn are misleading. Ideally, a test in this sort of
+      situation should not fail either. Instead, print an error
+      message by calling one of the DejaGnu procedures
+      <command>error</command> or <command>warning</command>.</para>
+
+    </sect1>
+
+    <sect1 id=tvariables xreflabel="Test Case Variables">
+      <title>Special variables used by test cases.</title>
+    
+      <para>There are special variables used by test cases. These contain
+      other information from DejaGnu. Your test cases can use these variables,
+      with conventional meanings (as well as the variables saved in
+      <filename>site.exp</filename>. You can use the value of these variables,
+      but they should never be changed.</para>
+
+        <variablelist>
+          <varlistentry>
+            <term>$prms_id</term>
+	    <listitem><para>The tracking system (e.g. GNATS) number identifying
+	    a corresponding bugreport.  (<emphasis>0</emphasis>} if you do not
+	    specify it in the test script.)</para></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>$item bug_id</term>
+	    <listitem><para>An optional bug id; may reflect a bug
+	    identification from another organization.  (<emphasis>0</emphasis>
+	    if you do not specify it.)</para></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>$subdir</term>
+	    <listitem><para>The subdirectory for the current test
+	    case.</para></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>$expect_out(buffer)</term>
+	    <listitem><para>The output from the last command. This is an
+	    internal variable set by Expect. More information can be found in
+	    the Expect manual.</para></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>$exec_output</term>
+	    <listitem><para>This is the output from a
+	    <function>${tool}_load</function> command. This only applies to
+	    tools like GCC and GAS which produce an object file that must in
+	    turn be executed to complete a test.</para></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>$comp_output</term>
+	    <listitem><para>This is the output from a
+	    <function>${tool}_start</function> command.  This is conventionally
+	    used for batch oriented programs, like GCC and GAS, that may
+	    produce interesting output (warnings, errors) without further
+	    interaction.</para></listitem> 
+          </varlistentry>
+        </variablelist>
+
+    </sect1>
+   
+</chapter>
+