SGML doc ported to DocBook 4.2 XML with GNOME help support.

8 files changed, 9163 insertions, 0 deletions

diff --git a/doc/C/Makefile.am b/doc/C/Makefile.am
new file mode 100644
index 0000000..bc03fd1
--- /dev/null
+++ b/doc/C/Makefile.am
@@ -0,0 +1,84 @@
+
+figdir = images
+docname = dejagnu
+lang = C
+omffile = dejagnu.omf
+
+entities = $(srcdir)/legal.xml
+include $(top_srcdir)/doc/xmldocs.make
+dist-hook: app-dist-hook
+gnuae_helpdir = $(datadir)/gnome/help/$(docname)/C
+
+CLEANFILES = \
+	db2texi.refs \
+	DejaGnu.texi \
+	DejaGnu.info \
+	dejagnu.txml \
+	dejagnu.mxml \
+	dejagnu.tex \
+	dejagnu.texi \
+	dejagnu.pdf \
+	dejagnu.ps \
+	dejagnu.rtf \
+	omf_timestamp \
+	manpages.ref 
+
+
+gnuae_help_DATA =    \
+        topic.dat    \
+	dejagnu.xml \
+	ref.xml \
+	user.xml
+
+MAKEINFO = @MAKEINFO@
+
+#html: force
+#	mkdir -p html/stylesheet
+#	cp -r $(srcdir)/images/*.png html/stylesheet
+#	xsltproc -v -o html/ $(srcdir)/stylesheets/general-customization.xsl $(srcdir)/dejagnu.xml
+
+clean-local: force
+	rm -fr html DejaGnu.info*
+
+html: force
+	docbook2html -o html $(srcdir)/dejagnu.xml
+	mv html/t1.html html/index.html
+
+pdf: force
+	docbook2pdf $(srcdir)/dejagnu.xml
+
+ps: force
+	docbook2ps $(srcdir)/dejagu.xml
+
+rtf: force
+	docbook2rtf $(srcdir)/dejagnu.xml
+
+man: force
+	db2x_xsltproc -s man $(srcdir)/dejagnu.xml -o dejagnu.mxml
+	db2x_manxml dejagnu.mxml
+#	docbook2man $(srcdir)/dejagnu.xml
+
+texi: force
+	db2x_xsltproc -s texi $(srcdir)/dejagnu.xml -o dejagnu.txml
+	db2x_texixml dejagnu.txml
+#	docbook2texi $(srcdir)/dejagnu.xml
+
+info: texi
+	$(MAKEINFO) DejaGnu.texi
+
+lint:
+	xmllint $(srcdir)/dejagnu.xml
+
+# install GNOME help files, which are basically the html output
+install-ghelp: html
+	$(mkinstalldirs) $(gnuae_helpdir)/stylesheet
+	$(mkinstalldirs) $(gnuae_helpdir)/images
+	$(INSTALL_DATA) html/*.html $(gnuae_helpdir)
+	$(INSTALL_DATA) html/stylesheet/*.png $(gnuae_helpdir)/stylesheet
+#	cp -r $(srcdir)/images $(gnuae_helpdir)/images
+
+force:
+
+scrollkeeper:
+	scrollkeeper-install $(prefix)/dejagnu.omf
+	scrollkeeper-update $(prefix)/dejagnu.omf
diff --git a/doc/C/Makefile.in b/doc/C/Makefile.in
new file mode 100644
index 0000000..564d66d
--- /dev/null
+++ b/doc/C/Makefile.in
@@ -0,0 +1,512 @@
+# Makefile.in generated by automake 1.7a from Makefile.am.
+# @configure_input@
+
+# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
+# 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.
+
+@SET_MAKE@
+
+#
+# No modifications of this Makefile should be necessary.
+#
+# To use this template:
+#     1) Define: figdir, docname, lang, omffile, and entities in
+#        your Makefile.am file for each document directory,
+#        although figdir, omffile, and entities may be empty
+#     2) Make sure the Makefile in (1) also includes 
+#	 "include $(top_srcdir)/doc/xmldocs.make and
+#	 "dist-hook: app-dist-hook".
+#     3) Optionally define 'entities' to hold xml entities which
+#        you would also like installed
+#     4) Figures must go under $(figdir)/ and be in PNG format
+#     5) You should only have one document per directory 
+#     6) Note that the figure directory, $(figdir)/, should not have its
+#        own Ma fdl-appendix.xmlkefile since this Makefile installs those figures.
+#
+# example Makefile.am:
+#   figdir = figures
+#   docname = scrollkeeper-manual
+#   lang = C
+#   omffile=scrollkeeper-manual-C.omf
+#   entities = fdl.xml
+#   include $(top_srcdir)/help/xmldocs.make
+#   dist-hook: app-dist-hook
+#
+# About this file:
+#	This file was taken from scrollkeeper_example2, a package illustrating
+#	how to install documentation and OMF files for use with ScrollKeeper 
+#	0.3.x and 0.4.x.  For more information, see:
+#		http://scrollkeeper.sourceforge.net/
+#	Version: 0.1.2 (last updated: March 20, 2002)
+#
+
+# 
+# No modifications of this Makefile should be necessary.
+#
+# This file contains the build instructions for installing OMF files.  It is
+# generally called from the makefiles for particular formats of documentation.
+#
+# Note that you must configure your package with --localstatedir=/var/lib
+# so that the scrollkeeper-update command below will update the database
+# in the standard scrollkeeper directory.
+#
+# If it is impossible to configure with --localstatedir=/var/lib, then
+# modify the definition of scrollkeeper_localstate_dir so that
+# it points to the correct location. Note that you must still use 
+# $(localstatedir) in this or when people build RPMs it will update
+# the real database on their system instead of the one under RPM_BUILD_ROOT.
+#
+# Note: This make file is not incorporated into xmldocs.make because, in
+#       general, there will be other documents install besides XML documents
+#       and the makefiles for these formats should also include this file.
+#
+# About this file:
+#	This file was taken from scrollkeeper_example2, a package illustrating
+#	how to install documentation and OMF files for use with ScrollKeeper
+#	0.3.x and 0.4.x.  For more information, see:
+#		http://scrollkeeper.sourceforge.net/	
+# 	Version: 0.1.2 (last updated: March 20, 2002)
+#
+
+srcdir = @srcdir@
+top_srcdir = @top_srcdir@
+VPATH = @srcdir@
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+top_builddir = ../..
+
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+INSTALL = @INSTALL@
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+ACLOCAL = @ACLOCAL@
+AMDEP_FALSE = @AMDEP_FALSE@
+AMDEP_TRUE = @AMDEP_TRUE@
+AMTAR = @AMTAR@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+BOARDS = @BOARDS@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+CONFIG = @CONFIG@
+CPPFLAGS = @CPPFLAGS@
+CXX = @CXX@
+CXXDEPMODE = @CXXDEPMODE@
+CXXFLAGS = @CXXFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DOCBOOK = @DOCBOOK@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EXEEXT = @EXEEXT@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+LDFLAGS = @LDFLAGS@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LTLIBOBJS = @LTLIBOBJS@
+MAINT = @MAINT@
+MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@
+MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@
+
+MAKEINFO = @MAKEINFO@
+OBJEXT = @OBJEXT@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+STRIP = @STRIP@
+TCLSH = @TCLSH@
+VERSION = @VERSION@
+YACC = @YACC@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_CXX = @ac_ct_CXX@
+ac_ct_STRIP = @ac_ct_STRIP@
+am__fastdepCC_FALSE = @am__fastdepCC_FALSE@
+am__fastdepCC_TRUE = @am__fastdepCC_TRUE@
+am__fastdepCXX_FALSE = @am__fastdepCXX_FALSE@
+am__fastdepCXX_TRUE = @am__fastdepCXX_TRUE@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+bindir = @bindir@
+build_alias = @build_alias@
+datadir = @datadir@
+exec_prefix = @exec_prefix@
+host_alias = @host_alias@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+oldincludedir = @oldincludedir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+subdirs = @subdirs@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+tclsh = @tclsh@
+
+figdir = images
+docname = dejagnu
+lang = C
+omffile = dejagnu.omf
+
+entities = $(srcdir)/legal.xml
+
+# ************* Begin of section some packagers may need to modify  **************
+# This variable (docdir) specifies where the documents should be installed.
+# This default value should work for most packages.
+docdir = $(datadir)/@PACKAGE@/doc/$(docname)/$(lang)
+
+# **************  You should not have to edit below this line  *******************
+xml_files = $(entities) $(docname).xml
+omf_dir = $(top_srcdir)/omf-install
+
+EXTRA_DIST = $(xml_files) $(omffile)
+
+CLEANFILES = \
+	db2texi.refs \
+	DejaGnu.texi \
+	DejaGnu.info \
+	dejagnu.txml \
+	dejagnu.mxml \
+	dejagnu.tex \
+	dejagnu.texi \
+	dejagnu.pdf \
+	dejagnu.ps \
+	dejagnu.rtf \
+	omf_timestamp \
+	manpages.ref 
+
+
+omf_dest_dir = $(datadir)/omf/@PACKAGE@
+scrollkeeper_localstate_dir = $(localstatedir)/scrollkeeper
+gnuae_helpdir = $(datadir)/gnome/help/$(docname)/C
+
+gnuae_help_DATA = \
+        topic.dat    \
+	dejagnu.xml \
+	ref.xml \
+	user.xml
+
+subdir = doc/C
+mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs
+CONFIG_CLEAN_FILES =
+DIST_SOURCES =
+DATA = $(gnuae_help_DATA)
+
+DIST_COMMON = $(top_srcdir)/doc/omf.make $(top_srcdir)/doc/xmldocs.make \
+	Makefile.am Makefile.in
+all: all-am
+
+.SUFFIXES:
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ Makefile.am $(top_srcdir)/doc/xmldocs.make $(top_srcdir)/doc/omf.make $(top_srcdir)/configure.in $(ACLOCAL_M4)
+	cd $(top_srcdir) && \
+	  $(AUTOMAKE) --gnu  doc/C/Makefile
+Makefile: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.in  $(top_builddir)/config.status
+	cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)
+uninstall-info-am:
+gnuae_helpDATA_INSTALL = $(INSTALL_DATA)
+install-gnuae_helpDATA: $(gnuae_help_DATA)
+	@$(NORMAL_INSTALL)
+	$(mkinstalldirs) $(DESTDIR)$(gnuae_helpdir)
+	@list='$(gnuae_help_DATA)'; for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  f="`echo $$p | sed -e 's|^.*/||'`"; \
+	  echo " $(gnuae_helpDATA_INSTALL) $$d$$p $(DESTDIR)$(gnuae_helpdir)/$$f"; \
+	  $(gnuae_helpDATA_INSTALL) $$d$$p $(DESTDIR)$(gnuae_helpdir)/$$f; \
+	done
+
+uninstall-gnuae_helpDATA:
+	@$(NORMAL_UNINSTALL)
+	@list='$(gnuae_help_DATA)'; for p in $$list; do \
+	  f="`echo $$p | sed -e 's|^.*/||'`"; \
+	  echo " rm -f $(DESTDIR)$(gnuae_helpdir)/$$f"; \
+	  rm -f $(DESTDIR)$(gnuae_helpdir)/$$f; \
+	done
+tags: TAGS
+TAGS:
+
+ctags: CTAGS
+CTAGS:
+
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+
+distdir: $(DISTFILES)
+	$(mkinstalldirs) $(distdir)/$(srcdir) $(distdir)/../../doc
+	@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+	topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \
+	list='$(DISTFILES)'; for file in $$list; do \
+	  case $$file in \
+	    $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
+	    $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \
+	  esac; \
+	  if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+	  dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \
+	  if test "$$dir" != "$$file" && test "$$dir" != "."; then \
+	    dir="/$$dir"; \
+	    $(mkinstalldirs) "$(distdir)$$dir"; \
+	  else \
+	    dir=''; \
+	  fi; \
+	  if test -d $$d/$$file; then \
+	    if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+	      cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \
+	    fi; \
+	    cp -pR $$d/$$file $(distdir)$$dir || exit 1; \
+	  else \
+	    test -f $(distdir)/$$file \
+	    || cp -p $$d/$$file $(distdir)/$$file \
+	    || exit 1; \
+	  fi; \
+	done
+	$(MAKE) $(AM_MAKEFLAGS) \
+	  top_distdir="$(top_distdir)" distdir="$(distdir)" \
+	  dist-hook
+check-am: all-am
+check: check-am
+all-am: Makefile $(DATA)
+
+installdirs:
+	$(mkinstalldirs) $(DESTDIR)$(gnuae_helpdir)
+
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+	@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+	$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	  INSTALL_STRIP_FLAG=-s \
+	  `test -z '$(STRIP)' || \
+	    echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
+mostlyclean-generic:
+
+clean-generic:
+	-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+	-rm -f Makefile $(CONFIG_CLEAN_FILES)
+
+maintainer-clean-generic:
+	@echo "This command is intended for maintainers to use"
+	@echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
+
+clean-am: clean-generic clean-local mostlyclean-am
+
+distclean: distclean-am
+
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am:
+
+info: info-am
+
+info-am:
+
+install-data-am: install-data-local install-gnuae_helpDATA
+	@$(NORMAL_INSTALL)
+	$(MAKE) $(AM_MAKEFLAGS) install-data-hook
+
+install-exec-am:
+
+install-info: install-info-am
+
+install-man:
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am: uninstall-gnuae_helpDATA uninstall-info-am uninstall-local
+
+.PHONY: all all-am check check-am clean clean-generic clean-local \
+	distclean distclean-generic distdir dvi dvi-am info info-am \
+	install install-am install-data install-data-am \
+	install-data-local install-exec install-exec-am \
+	install-gnuae_helpDATA install-info install-info-am install-man \
+	install-strip installcheck installcheck-am installdirs \
+	maintainer-clean maintainer-clean-generic mostlyclean \
+	mostlyclean-generic pdf pdf-am ps ps-am uninstall uninstall-am \
+	uninstall-gnuae_helpDATA uninstall-info-am uninstall-local
+
+
+omf: omf_timestamp
+
+omf_timestamp: $(omffile)
+	-for file in $(omffile); do \
+	  scrollkeeper-preinstall $(docdir)/$(docname).xml $(srcdir)/$$file $(srcdir)/$$file.out; \
+	done
+	touch omf_timestamp
+
+install-data-hook-omf:
+	$(mkinstalldirs) $(DESTDIR)$(omf_dest_dir)
+	for file in $(omffile); do \
+		$(INSTALL_DATA) $(srcdir)/$$file.out $(DESTDIR)$(omf_dest_dir)/$$file; \
+	done
+	-scrollkeeper-update -p $(scrollkeeper_localstate_dir) -o $(DESTDIR)$(omf_dest_dir)
+
+uninstall-local-omf:
+	-for file in $(srcdir)/*.omf; do \
+		basefile=`basename $$file`; \
+		rm -f $(omf_dest_dir)/$$basefile; \
+	done
+	-rmdir $(omf_dest_dir)
+	-scrollkeeper-update -p $(scrollkeeper_localstate_dir)
+
+all: omf
+
+$(docname).xml: $(entities)
+	-ourdir=`pwd`;  \
+	cd $(srcdir);   \
+	cp $(entities) $$ourdir
+
+app-dist-hook:
+	if test "$(figdir)"; then \
+	  $(mkinstalldirs) $(distdir)/$(figdir); \
+	  for file in $(srcdir)/$(figdir)/*.png; do \
+	    basefile=`echo $$file | sed -e  's,^.*/,,'`; \
+	    $(INSTALL_DATA) $$file $(distdir)/$(figdir)/$$basefile; \
+	  done \
+	fi
+
+install-data-local: omf
+	$(mkinstalldirs) $(DESTDIR)$(docdir)
+	for file in $(xml_files); do \
+	  cp $(srcdir)/$$file $(DESTDIR)$(docdir); \
+	done
+	if test "$(figdir)"; then \
+	  $(mkinstalldirs) $(DESTDIR)$(docdir)/$(figdir); \
+	  for file in $(srcdir)/$(figdir)/*.png; do \
+	    basefile=`echo $$file | sed -e  's,^.*/,,'`; \
+	    $(INSTALL_DATA) $$file $(DESTDIR)$(docdir)/$(figdir)/$$basefile; \
+	  done \
+	fi
+
+install-data-hook: install-data-hook-omf
+
+uninstall-local: uninstall-local-doc uninstall-local-omf
+
+uninstall-local-doc:
+	-if test "$(figdir)"; then \
+	  for file in $(srcdir)/$(figdir)/*.png; do \
+	    basefile=`echo $$file | sed -e  's,^.*/,,'`; \
+	    rm -f $(docdir)/$(figdir)/$$basefile; \
+	  done; \
+	  rmdir $(DESTDIR)$(docdir)/$(figdir); \
+	fi
+	-for file in $(xml_files); do \
+	  rm -f $(DESTDIR)$(docdir)/$$file; \
+	done
+	-rmdir $(DESTDIR)$(docdir)
+dist-hook: app-dist-hook
+
+#html: force
+#	mkdir -p html/stylesheet
+#	cp -r $(srcdir)/images/*.png html/stylesheet
+#	xsltproc -v -o html/ $(srcdir)/stylesheets/general-customization.xsl $(srcdir)/dejagnu.xml
+
+clean-local: force
+	rm -fr html DejaGnu.info*
+
+html: force
+	docbook2html -o html $(srcdir)/dejagnu.xml
+	mv html/t1.html html/index.html
+
+pdf: force
+	docbook2pdf $(srcdir)/dejagnu.xml
+
+ps: force
+	docbook2ps $(srcdir)/dejagu.xml
+
+rtf: force
+	docbook2rtf $(srcdir)/dejagnu.xml
+
+man: force
+	db2x_xsltproc -s man $(srcdir)/dejagnu.xml -o dejagnu.mxml
+	db2x_manxml dejagnu.mxml
+#	docbook2man $(srcdir)/dejagnu.xml
+
+texi: force
+	db2x_xsltproc -s texi $(srcdir)/dejagnu.xml -o dejagnu.txml
+	db2x_texixml dejagnu.txml
+#	docbook2texi $(srcdir)/dejagnu.xml
+
+info: texi
+	$(MAKEINFO) DejaGnu.texi
+
+lint:
+	xmllint $(srcdir)/dejagnu.xml
+
+# install GNOME help files, which are basically the html output
+install-ghelp: html
+	$(mkinstalldirs) $(gnuae_helpdir)/stylesheet
+	$(mkinstalldirs) $(gnuae_helpdir)/images
+	$(INSTALL_DATA) html/*.html $(gnuae_helpdir)
+	$(INSTALL_DATA) html/stylesheet/*.png $(gnuae_helpdir)/stylesheet
+#	cp -r $(srcdir)/images $(gnuae_helpdir)/images
+
+force:
+
+scrollkeeper:
+	scrollkeeper-install $(prefix)/dejagnu.omf
+	scrollkeeper-update $(prefix)/dejagnu.omf
+# 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/C/dejagnu.omf b/doc/C/dejagnu.omf
new file mode 100644
index 0000000..ddbedb0
--- /dev/null
+++ b/doc/C/dejagnu.omf
@@ -0,0 +1,27 @@
+<?xml version="1.0" standalone="no"?>
+<omf>
+  <resource>
+    <creator>
+     rob@senecass.com (Rob Savoye)
+    </creator>
+    <title>
+	DejaGnu Manual
+    </title>
+    <date>
+     2004-02-05
+    </date>
+    <version identifier="1.4.4" date="2004-02-05" description="First release.  Updated for new OMF DTD."/>
+    <subject category="System|Other"/>
+    <description>
+	This is the manual for DejaGnu, the GNU regression Testing Framework
+    </description>
+    <type>
+     manual
+    </type>
+    <format mime="text/xml" dtd="-//OASIS//DTD DocBook XML V4.1.2//EN"/>
+    <identifier url=""/>
+    <language code="C"/>
+    <relation seriesid="31a101ca-363a-11d6-93d3-b34a9c6ce2e6"/>
+    <rights type="GNU FDL" license.version="1.1" license="http://www.gnu.org/licenses/fdl.html" holder="Free Software Foundation"/>
+  </resource>
+</omf>
diff --git a/doc/C/dejagnu.xml b/doc/C/dejagnu.xml
new file mode 100644
index 0000000..dec8a95
--- /dev/null
+++ b/doc/C/dejagnu.xml
@@ -0,0 +1,455 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+  <!ENTITY legal SYSTEM "legal.xml">
+  <!ENTITY appversion "1.4.5">
+  <!ENTITY version "1.4.5">
+  <!ENTITY manrevision "1.0">
+  <!ENTITY date "Feb 2004">
+  <!ENTITY app "<application>DejaGnu</application>">
+  <!ENTITY appname "DejaGnu">
+  <!ENTITY dj "DejaGnu">
+  <!-- The reference material -->
+  <!ENTITY ref SYSTEM "ref.xml">
+  <!-- The user manual -->
+  <!ENTITY user SYSTEM "user.xml">
+]>
+<!-- Begin Document Specific Declarations -->
+<article>
+  <articleinfo>
+    <title>&dj;</title>
+    <subtitle>The GNU Testing Framework</subtitle>
+    <date>2004 Feb 04</date>
+    <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>
+       <year>2004</year>
+       <holder>Rob Savoye</holder>
+    </copyright>
+    <!-- <legalnotice>
+      <para> -->
+        <!-- [FIXME: must put legal notice here] -->
+      <!-- </para> -->
+      <!-- &cygnus-legal-notice; -->
+    <!-- </legalnotice> -->
+    <revhistory>
+      <revision>
+        <revnumber>0.6.2</revnumber>
+        <date>2002-7-16</date>
+        <authorinitials>rob@welcomehome.org</authorinitials>
+        <revremark>Add new tutorial as a new sect1.</revremark>
+      </revision>
+      <revision>
+        <revnumber>0.6.1</revnumber>
+        <date>2001-2-16</date>
+        <authorinitials>rob@welcomehome.org</authorinitials>
+        <revremark>Add info on the new dejagnu.h file.</revremark>
+      </revision>
+      <revision>
+        <revnumber>0.6</revnumber>
+        <date>2001-2-16</date>
+        <authorinitials>rob@welcomehome.org</authorinitials>
+        <revremark>Updated for new release.</revremark>
+      </revision>
+      <revision>
+        <revnumber>0.5</revnumber>
+        <date>2000-1-24</date>
+        <authorinitials>rob@welcomehome.org</authorinitials>
+        <revremark>Initial version after conversion to DocBook.</revremark>
+      </revision>
+    </revhistory>
+
+  </articleinfo>
+
+ <sect1 id="preface">
+    <title>Abstract</title>
+
+    <para>This document describes the functionality of DejaGnu, the
+    testing framework of the GNU project. DejaGnu is written in
+    <productname>Expect</productname>, which uses
+    <productname>Tcl</productname> as a command
+    language. <productname>Expect</productname> acts as a very
+    programmable shell.  As with other Unix command shells, you can
+    run any program, but once the program is started, your test script
+    has programmable control over 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 the creation of
+    testsuites. Testsuites are distributed with each
+    application.</para>
+
+  </sect1>
+
+  <sect1 id="overview" xreflabel="Overview">
+    <title>Overview</title>
+    <sect2 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 testsuites, 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>Julia Menapace first coined the term ``DejaGnu'' 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.
+        More importantly, it was also named after my daughter, <ulink
+        url="mailto:deja@welcomehome.org">Deja Snow Savoye</ulink>
+        (now 14 years old as of Feb 2004), who was a toddler
+        during DejaGnu's beginnings.</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 supported host
+	system on any supported target system. DejaGnu runs tests on
+	many single board computers, whose operating software ranges
+	from a simple boot monitor to a real-time 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 testsuites. 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 testsuites themselves. Tests are usually written in
+    <productname>Expect</productname> using Tcl, but you can also use
+    a Tcl script to run a testsuite 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>
+	
+  </sect2>
+
+  <sect2 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 built-in 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>Windows support. There is beta level support for
+      Windows that is still a work in progress. This requires the
+      <ulink url="http://www.cygwin.com/">Cygwin</ulink> POSIX
+      subsystem for Windows.</para></listitem>
+
+    </itemizedlist>
+
+    <sect3 id="cygwin" xreflabel="Windows Support">
+      <title>Windows Support</title>
+
+      <para>To use DejaGnu on Windows, you need to first install the
+	<ulink url="http://www.cygwin.com/">Cygwin</ulink>
+	release. This works as of the B20.1 release. Cygwin is a POSIX
+	system for Windows. This covers both utility programs and a library
+	that adds POSIX system calls to Windows. Among them is pseudo tty
+	support for Windows that emulates the POSIX pty standard. The
+	latest Cygwin is always available from <ulink
+	url="http://www.cygwin.com/">this location</ulink>. This
+	works well enough to run <emphasis>"make check"</emphasis> of
+	the GNU development tree on Windows after a native build. But the
+	nature of ptys on Windows is still evolving. Your mileage may
+	vary.</para>
+
+    </sect3>
+	
+  </sect2>
+
+  <sect2 id="designgoals" xreflabel="Design Goals">
+    <title>Design Goals</title>
+
+    <para>DejaGnu grew out of the internal needs of Cygnus Solutions,
+    the company formerly known as Cygnus Support. Cygnus maintained
+    and enhanced a variety of free programs in many different
+    environments and we needed a testing tool that:</para>
+
+    <itemizedlist mark="bullet">
+      <listitem><para>was useful to developers while fixing
+      bugs;</para></listitem>
+      <listitem><para>automated running many tests during a software
+      release process;</para></listitem>
+      <listitem><para>was portable among a variety of host
+      computers;</para></listitem>
+      <listitem><para>supported cross-development
+      testing;</para></listitem>
+      <listitem><para>permitted testing interactive programs, like
+      <command>GDB</command>; and </para></listitem>
+      <listitem><para>permitted testing batch oriented programs, like
+      <command>GCC</command>.</para></listitem>
+    </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.  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>
+
+    </sect2>
+
+    <sect2 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. Rob Savoye was a member of that committee.</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 day or night.  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 testsuite 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 testsuite
+      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 commands 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></listitem>
+
+	</varlistentry>
+	</variablelist>
+
+          <itemizedlist>
+	    <listitem><para>A test's execution is
+	    interrupted.</para></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>
+
+	<variablelist>
+	  <varlistentry>
+	    <term>UNTESTED</term>
+	    <listitem><para>A test was not run.  This is a place-holder, used
+	    when there is no real test case yet.</para></listitem>
+	  </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.</para></listitem>
+	  </varlistentry>
+	</variablelist>
+
+        <para>DejaGnu uses the same output procedures to produce these messages
+	for all testsuites and these procedures are already known to conform
+	to POSIX 1003.3.  For a DejaGnu testsuite 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>
+     </sect2>
+  </sect1>
+
+  <!-- include the user manual -->
+  &user;
+
+  <!-- include the reference manual -->
+  &ref;
+
+</article>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:nil
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/C/legal.xml b/doc/C/legal.xml
new file mode 100644
index 0000000..ac97e1d
--- /dev/null
+++ b/doc/C/legal.xml
@@ -0,0 +1,76 @@
+  <legalnotice id="legalnotice">
+	<para>
+	  Permission is granted to copy, distribute and/or modify this
+	  document under the terms of the GNU Free Documentation
+	  License (GFDL), Version 1.1 or any later version published
+	  by the Free Software Foundation with no Invariant Sections,
+	  no Front-Cover Texts, and no Back-Cover Texts.  You can find
+	  a copy of the GFDL at this <ulink type="help"
+	  url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS
+	  distributed with this manual.
+         </para>
+         <para> This manual is part of a collection of GNOME manuals
+          distributed under the GFDL.  If you want to distribute this
+          manual separately from the collection, you can do so by
+          adding a copy of the license to the manual, as described in
+          section 6 of the license.
+	</para>
+
+	<para>
+	  Many of the names used by companies to distinguish their
+	  products and services are claimed as trademarks. Where those
+	  names appear in any GNOME documentation, and the members of
+	  the GNOME Documentation Project are made aware of those
+	  trademarks, then the names are in capital letters or initial
+	  capital letters.
+	</para>
+
+	<para>
+	  DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED
+	  UNDER  THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE
+	  WITH THE FURTHER UNDERSTANDING THAT:
+
+	  <orderedlist>
+		<listitem>
+		  <para>DOCUMENT IS PROVIDED ON AN "AS IS" BASIS,
+                    WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
+                    IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES
+                    THAT THE DOCUMENT OR MODIFIED VERSION OF THE
+                    DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR
+                    A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE
+                    RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE
+                    OF THE DOCUMENT OR MODIFIED VERSION OF THE
+                    DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR
+                    MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT,
+                    YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY
+                    CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY
+                    SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER
+                    OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS
+                    LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED
+                    VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER
+                    EXCEPT UNDER THIS DISCLAIMER; AND
+		  </para>
+		</listitem>
+		<listitem>
+		  <para>UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL
+                       THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE),
+                       CONTRACT, OR OTHERWISE, SHALL THE AUTHOR,
+                       INITIAL WRITER, ANY CONTRIBUTOR, OR ANY
+                       DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION
+                       OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH
+                       PARTIES, BE LIABLE TO ANY PERSON FOR ANY
+                       DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
+                       CONSEQUENTIAL DAMAGES OF ANY CHARACTER
+                       INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS
+                       OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR
+                       MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR
+                       LOSSES ARISING OUT OF OR RELATING TO USE OF THE
+                       DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT,
+                       EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF
+                       THE POSSIBILITY OF SUCH DAMAGES.
+		  </para>
+		</listitem>
+	  </orderedlist>
+	</para>
+  </legalnotice>
+
diff --git a/doc/C/ref.xml b/doc/C/ref.xml
new file mode 100644
index 0000000..e603d04
--- /dev/null
+++ b/doc/C/ref.xml
@@ -0,0 +1,4827 @@
+
+<sect1 id="reference">
+  <title>Reference</title>
+
+  <sect2 id="obtaining" xreflabel="Obtaining DejaGnu">
+    <title>Obtaining DejaGnu</title>
+
+    <para>You can obtain DejaGnu from the DejaGnu web site at the
+    <ulink url="http://www.gnu.org">Free Software Foundation</ulink>,
+    which is at <ulink
+    url="http://www.gnu.org/software/dejagnu/">www.gnu.org/software/dejagnu/
+    </ulink></para>
+
+  </sect2>
+
+  <sect2 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>
+
+    <sect3 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-&version;/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 testsuites; these are available
+      separately. Testsuites 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>
+
+    </sect3>
+
+    <sect3 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.</para></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.</para></listitem>
+
+	<listitem><para>Copy the <emphasis>runtest</emphasis> shell script into
+	<filename>$exec_prefix/bin</filename>.</para></listitem>
+
+	<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>
+  </sect3>
+  </sect2>
+
+  <sect2 id="builtins" xreflabel="Builtin Procedures">
+    <title>Builtin Procedures</title>
+
+    <para>DejaGnu provides these Tcl procedures.</para>
+
+    <sect3 id="coreprocs" xreflabel="Core Internal Procedures">
+      <title>Core Internal Procedures</title>
+
+      <sect4 id="mailfile" xreflabel="mail_file procedure">
+        <title>Mail_file Procedure</title>
+
+	<funcsynopsis role="tcl">
+           <funcprototype>
+             <funcdef><function>mail_file</function></funcdef>
+	     <paramdef><parameter>file to
+	     subject</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+      <sect4 id="openlogs" xreflabel="open_logs procedure">
+        <title>Open_logs Procedure</title>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>open_logs</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 id="closelogs" xreflabel="close_logs procedure">
+	  <title>Close_logs Procedure</title>
+
+	  <para></para>	
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>close_logs</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>isbuild</function></funcdef>
+	    <paramdef><parameter>pattern</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>pattern</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="isremote" xreflabel="is_remote procedure">
+	  <title>Is_remote Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>is_remote</function></funcdef>
+	    <paramdef><parameter>board</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>is3way</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>	
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>ishost</function></funcdef>
+	    <paramdef><parameter>pattern</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>istarget</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>isnative</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 id="unknown" xreflabel="unknown procedure">
+	  <title>Unknown Procedure</title>
+
+	  <para></para>	
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>unknown</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="cloneoutput" xreflabel="clone_output procedure">
+	  <title>Clone_output Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>clone_output</function></funcdef>
+	    <paramdef><parameter>message</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>message</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="resetvars" xreflabel="reset_vars procedure">
+	  <title>Reset_vars Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>reset_vars</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>	
+
+	<sect4 id="logandexit" xreflabel="log_and_exit procedure">
+	  <title>Log_and_exit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>log_and_exit</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>	
+
+	<sect4 id="logsummary" xreflabel="log_summary procedure">
+	  <title>Log_summary Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>log_summary</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>	
+
+	<sect4 id="cleanup" xreflabel="cleanup procedure">
+	  <title>Cleanup Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>cleanup</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>setup_xfail</function></funcdef>
+	    <paramdef><parameter>config</parameter>
+	    <parameter>bugid</parameter></paramdef>
+           </funcprototype>
+        </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>
+      </sect4>
+
+	<sect4 id="recordtest" xreflabel="record_test procedure">
+	  <title>Record_test Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>record_test</function></funcdef>
+	    <paramdef><parameter>type</parameter>
+		<parameter>message</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>pass</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this PASS
+	    message.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>fail</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this FAIL
+	    message.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>xpass</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this output
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>xpass</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this output
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>set_warning_threshold</function></funcdef>
+	    <paramdef><parameter>threshold</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>threshold</parameter></term>
+	    <listitem><para>This is the value of the new warning
+	    threshold.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>get_warning_threshold</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+
+      </sect4>
+      <sect4 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">
+          <funcprototype>
+            <funcdef><function>warning</function></funcdef>
+	    <paramdef><parameter>string</parameter>
+	    <parameter>number</parameter>
+	    </paramdef>
+           </funcprototype>
+        </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>
+
+      </sect4>
+      <sect4 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">
+          <funcprototype>
+            <funcdef><function>perror</function></funcdef>
+	    <paramdef><parameter>string</parameter>
+	    <parameter>number</parameter>
+	    </paramdef>
+           </funcprototype>
+        </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>
+
+      </sect4>
+       <sect4 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">
+          <funcprototype>
+            <funcdef><function>note</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this note.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+       <sect4 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">
+          <funcprototype>
+            <funcdef><function>untested</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this output
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+       <sect4 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">
+          <funcprototype>
+            <funcdef><function>unresolved</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this output
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+       <sect4 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">
+          <funcprototype>
+            <funcdef><function>unsupported</function></funcdef>
+	    <paramdef><parameter>string</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>string</parameter></term>
+	    <listitem><para>The string to use for this output
+	    state.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="inittestcounts" xreflabel="init_testcounts procedure">
+	  <title>Init_testcounts Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>init_testcounts</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 id="incrcount" xreflabel="incr_count procedure">
+	  <title>Incr_count Procedure</title>
+
+	  <para></para>	
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>incr_count</function></funcdef>
+	    <paramdef><parameter>name</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>transform</function></funcdef>
+	    <paramdef><parameter>toolname</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>toolname</parameter></term>
+	    <listitem><para>The name of the cross-development program to
+	    transform.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+
+	<sect4 id="checkconditionalxfail" xreflabel="check_conditional_xfail procedure">
+	  <title>Check_conditional_xfail Procedure</title>
+
+	  <para>This procedure adds a conditional 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">
+          <funcprototype>
+            <funcdef><function>check_conditional_xfail</function></funcdef>
+	    <paramdef><parameter>message</parameter>
+	    <parameter>targets</parameter>
+	    <parameter>includes</parameter>
+	    <parameter>excludes</parameter></paramdef>
+           </funcprototype>
+        </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 the list of
+	    sets of options is empty or if any set of the options matches,
+	    then this conditional is true.  (It may be useful to specify an
+	    empty list of include sets if the conditional is always true
+	    unless one of the exclude sets matches.)</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>
+
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>clear_xfail</function></funcdef>
+	    <paramdef><parameter>config</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>config</parameter></term>
+ 	    <listitem><para>The configuration triplets to
+ 	    clear.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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>-x</option> argument to log the test results into
+          a parsable XML file.  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">
+          <funcprototype>
+            <funcdef><function>verbose</function></funcdef>
+	    <paramdef><parameter>-log</parameter>
+            <parameter>-x</parameter>
+	    <parameter>-n</parameter>
+	    <parameter>-r</parameter>
+	    <parameter>string</parameter>
+	    <parameter>number</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+            <term><parameter>-x</parameter></term>
+            <listitem><para></para></listitem>
+          </varlistentry>
+          <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>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>load_lib</function></funcdef>
+	    <paramdef><parameter>filespec</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>filespec</parameter></term>
+ 	    <listitem><para>The name of the DejaGnu library file to
+	    load.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+    </sect3>
+
+    <sect3 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>
+
+	<sect4 id="callremote" xreflabel="call_remote procedure">
+	  <title>Call_remote Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>call_remote</function></funcdef>
+	    <paramdef><parameter>type</parameter>
+		<parameter>proc</parameter>
+		<parameter>dest</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	 </sect4>
+
+	 <sect4 id="checkforboardstatus" xreflabel="check_for_board_status
+	 procedure">
+	   <title>Check_for_board_status Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>check_for_board_status</function></funcdef>
+	    <paramdef><parameter>variable</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+             <varlistentry>
+	       <term><parameter>variable</parameter></term>
+	        <listitem><para></para></listitem>
+         </varlistentry>
+         </variablelist>
+	 </sect4>
+
+	 <sect4 id="fileonbuild" xreflabel="file_on_build procedure">
+	   <title>File_on_build Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>file_on_build</function></funcdef>
+	    <paramdef><parameter>op</parameter>
+		<parameter>file</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	 </sect4>
+
+	 <sect4 id="fileonhost" xreflabel="file_on_host procedure">
+	   <title>File_on_host Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>file_on_host</function></funcdef>
+	    <paramdef><parameter>op</parameter>
+		<parameter>file</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	 </sect4>
+
+	 <sect4 id="localexec" xreflabel="local_exec procedure">
+	   <title>Local_exec Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>local_exec</function></funcdef>
+	    <paramdef><parameter>commandline</parameter>
+		<parameter>inp</parameter>
+		<parameter>outp</parameter>
+		<parameter>timeout</parameter></paramdef>
+           </funcprototype>
+        </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>
+	 </sect4>
+
+	 <sect4 id="remotebinary" xreflabel="remote_binary procedure">
+	   <title>Remote_binary Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_binary</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	     <term><parameter>host</parameter></term>
+	     <listitem><para></para></listitem>
+           </varlistentry>
+         </variablelist>
+	 </sect4>
+
+	 <sect4 id="remoteclose" xreflabel="remote_close procedure">
+	   <title>Remote_close Procedure</title>
+
+	   <para></para>	
+
+	  <funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_close</function></funcdef>
+	    <paramdef><parameter>shellid</parameter></paramdef>
+           </funcprototype>
+          </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>
+	 </sect4>
+
+	 <sect4 id="remotedownload" xreflabel="remote_download procedure">
+	   <title>Remote_download Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+          <funcdef><function>remote_download</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoteexec" xreflabel="remote_exec procedure">
+	  <title>Remote_exec Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_exec</function></funcdef>
+	    <paramdef><parameter>hostname</parameter>
+		<parameter>program</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoteexpect" xreflabel="remote_expect procedure">
+	  <title>Remote_expect Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_expect</function></funcdef>
+	    <paramdef><parameter>board</parameter>
+		<parameter>timeout</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remotefile" xreflabel="remote_file procedure">
+	  <title>Remote_file Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_file</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoteld" xreflabel="remote_ld procedure">
+	  <title>Remote_ld Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_ld</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>prog</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoteload" xreflabel="remote_load procedure">
+	  <title>Remote_load Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_load</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>prog</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoteopen" xreflabel="remote_open procedure">
+	  <title>Remote_open Procedure</title>
+
+	  <para></para>
+
+	  <funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_open</function></funcdef>
+	      <paramdef><parameter>type</parameter></paramdef>
+           </funcprototype>
+            </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>
+	 </sect4>
+
+	 <sect4 id="remotepopconn" xreflabel="remote_pop_conn procedure">
+	   <title>Remote_pop_conn Procedure</title>
+
+	   <para></para>	
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_pop_conn</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="remotepushconn" xreflabel="remote_push_conn procedure">
+	  <title>Remote_push_conn Procedure</title>
+
+	  <para></para>	
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_push_conn</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="remoterawbinary" xreflabel="remote_raw_binary procedure">
+	  <title>Remote_raw_binary Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_raw_binary</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="remoterawclose" xreflabel="remote_raw_close procedure">
+	  <title>Remote_raw_close Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_raw_close</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="remoterawfile" xreflabel="remote_raw_file procedure">
+	  <title>Remote_raw_file Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_raw_file</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoterawld" xreflabel="remote_raw_ld procedure">
+	  <title>remote_raw_ld Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_raw_ld</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>prog</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoterawload" xreflabel="remote_raw_load procedure">
+	  <title>Remote_raw_load Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_raw_load</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>prog</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoterawopen" xreflabel="remote_raw_open procedure">
+	  <title>Remote_raw_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_raw_open</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="remoterawsend" xreflabel="remote_raw_send procedure">
+	  <title>Remote_raw_send Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_raw_send</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>string</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoterawspawn" xreflabel="remote_raw_spawn procedure">
+	  <title>Remote_raw_spawn Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_raw_spawn</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>commandline</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoterawtransmit" xreflabel="remote_raw_transmit
+	procedure">
+	  <title>Remote_raw_transmit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_raw_transmit</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoterawwait" xreflabel="remote_raw_wait procedure">
+	  <title>Remote_raw_wait Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_raw_wait</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>timeout</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remotereboot" xreflabel="remote_reboot procedure">
+	  <title>Remote_reboot Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_reboot</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="remotesend" xreflabel="remote_send procedure">
+	  <title>Remote_send Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_send</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>string</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remotespawn" xreflabel="remote_spawn procedure">
+	  <title>Remote_spawn Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_spawn</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>commandline</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoteswapconn" xreflabel="remote_swap_conn procedure">
+	  <title>Remote_swap_conn Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_swap_conn</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="remotetransmit" xreflabel="remote_transmit procedure">
+	  <title>Remote_transmit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_transmit</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remoteupload" xreflabel="remote_upload procedure">
+	  <title>Remote_upload Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_upload</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>srcfile</parameter>
+		<parameter>arg</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="remotewait" xreflabel="remote_wait procedure">
+	  <title>Remote_wait Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>remote_wait</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>timeout</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="standardclose" xreflabel="standard_close procedure">
+	  <title>Standard_close Procedure</title>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_close</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="standarddownload" xreflabel="standard_download procedure">
+	  <title>Standard_download Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_download</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter>
+		<parameter>destfile</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="standardexec" xreflabel="standard_exec procedure">
+	  <title>Standard_exec Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_exec</function></funcdef>
+	    <paramdef><parameter>hostname</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="standardfile" xreflabel="standard_file procedure">
+	  <title>Standard_file Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_file</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>op</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="standardload" xreflabel="standard_load procedure">
+	  <title>Standard_load Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_load</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>prog</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="standardreboot" xreflabel="standard_reboot procedure">
+	  <title>Standard_reboot Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_reboot</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="standardsend" xreflabel="standard_send procedure">
+	  <title>Standard_send Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_send</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>string</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="standardspawn" xreflabel="standard_spawn procedure">
+	  <title>Standard_spawn Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_spawn</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>commandline</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="standardtransmit" xreflabel="standard_transmit procedure">
+	  <title>Standard_transmit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_transmit</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="standardupload" xreflabel="standard_upload procedure">
+	  <title>Standard_upload Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_upload</function></funcdef>
+	    <paramdef><parameter>dest srcfile destfile</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="standardwait" xreflabel="standard_wait procedure">
+	  <title>Standard_wait Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>standard_wait</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>timeout</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="unixcleanfilename" xreflabel="unix_clean_filename
+	procedure">
+	  <title>Unix_clean_filename Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>unix_clean_filename</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+<!-- FIXME: this doesn't seem to exist anymore
+	<sect4 id="exitremoteshell" xreflabel="exit_remote_shell procedure">
+	  <title>exit_remote_shell Procedure</title>
+
+	  <para></para>
+
+          <funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>exit_remote_shell</function></funcdef>
+              <paramdef><parameter>spawnid</parameter></paramdef>
+           </funcprototype>
+            </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>
+	 </sect4>
+-->
+
+    </sect3>
+
+    <sect3 id="connprocs" xreflabel="connprocs">
+      <title>Procedures For Using Utilities to Connect</title>
+
+      <para>telnet, rsh, tip, kermit</para>
+
+      <sect4 id="telnet" xreflabel="telnet procedure">
+        <title>telnet Procedure</title>
+
+	<para></para>
+
+	  <funcsynopsis role="tcl">
+          <funcprototype>
+	    <funcdef><function>telnet</function></funcdef>
+	    <paramdef><parameter>hostname</parameter>
+	    <parameter>port</parameter></paramdef>
+           </funcprototype>
+          </funcsynopsis>
+          <funcsynopsis role="tcl">
+          <funcprototype>
+	    <funcdef><function>rlogin</function></funcdef>
+	    <paramdef><parameter>hostname</parameter></paramdef>
+           </funcprototype>
+          </funcsynopsis>
+	  </sect4>
+
+	  <sect4 id="rsh" xreflabel="rsh procedure">
+	    <title>rsh Procedure</title>
+
+	    <para></para>
+
+          <funcsynopsis role="tcl">
+          <funcprototype>
+	    <funcdef><function>rsh</function></funcdef>
+	    <paramdef><parameter>hostname</parameter></paramdef>
+           </funcprototype>
+          </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>
+	 </sect4>
+
+	 <sect4 id="tip" xreflabel="tip procedure">
+	   <title>Tip Procedure</title>
+
+	   <para></para>
+
+	 <funcsynopsis role="tcl">
+          <funcprototype>
+           <funcdef><function>tip</function></funcdef>
+            <paramdef><parameter>port</parameter></paramdef>
+           </funcprototype>
+          </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>
+	 </sect4>
+
+	 <sect4 id="kermit" xreflabel="kermit procedure">
+	   <title>Kermit Procedure</title>
+
+	   <para></para>
+
+          <funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>kermit</function></funcdef>
+            <paramdef><parameter>port</parameter>
+	    <parameter>bps</parameter></paramdef>
+           </funcprototype>
+          </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>
+	 </sect4>
+
+	 <sect4 id="kermitopen" xreflabel="kermit_open procedure">
+	   <title>kermit_open Procedure</title>
+
+	   <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>kermit_open</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="kermitcommand" xreflabel="kermit_command procedure">
+	  <title>Kermit_command Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>kermit_command</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="kermitsend" xreflabel="kermit_send procedure">
+	  <title>Kermit_send Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>kermit_send</function></funcdef>
+	    <paramdef><parameter>dest string args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="kermittransmit" xreflabel="kermit_transmit procedure">
+	  <title>Kermit_transmit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>kermit_transmit</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="telnetopen" xreflabel="telnet_open procedure">
+	  <title>Telnet_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>telnet_open</function></funcdef>
+	    <paramdef><parameter>hostname</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="telnetbinary" xreflabel="telnet_binary procedure">
+	  <title>Telnet_binary Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>telnet_binary</function></funcdef>
+	    <paramdef><parameter>hostname</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>hostname</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="telnettransmit" xreflabel="telnet_transmit procedure">
+	  <title>Telnet_transmit Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>telnet_transmit</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>file</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="tipopen" xreflabel="tip_open procedure">
+	  <title>Tip_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>tip_open</function></funcdef>
+	    <paramdef><parameter>hostname</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>hostname</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="rloginopen" xreflabel="rlogin_open procedure">
+	  <title>Rlogin_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>rlogin_open</function></funcdef>
+	    <paramdef><parameter>arg</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>arg</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="rloginspawn" xreflabel="rlogin_spawn procedure">
+	  <title>Rlogin_spawn Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>rlogin_spawn</function></funcdef>
+	    <paramdef><parameter>dest</parameter>
+		<parameter>cmdline</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="rshopen" xreflabel="rsh_open procedure">
+	  <title>Rsh_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>rsh_open</function></funcdef>
+	    <paramdef><parameter>hostname</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>hostname</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="rshdownload" xreflabel="rsh_download procedure">
+	  <title>Rsh_download Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>rsh_download</function></funcdef>
+	    <paramdef><parameter>desthost</parameter>
+		<parameter>srcfile</parameter>
+		<parameter>destfile</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="rshupload" xreflabel="rsh_upload procedure">
+	  <title>Rsh_upload Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>rsh_upload</function></funcdef>
+	    <paramdef><parameter>desthost</parameter>
+		<parameter>srcfile</parameter>
+		<parameter>destfile</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="rshexec" xreflabel="rsh_exec procedure">
+	  <title>Rsh_exec Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>rsh_exec</function></funcdef>
+	    <paramdef><parameter>boardname</parameter>
+		<parameter>cmd</parameter>
+		<parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="ftpopen" xreflabel="ftp_open procedure">
+	  <title>Ftp_open Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>ftp_open</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="ftpupload" xreflabel="ftp_upload procedure">
+	  <title>Ftp_upload Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>ftp_upload</function></funcdef>
+	    <paramdef><parameter>host</parameter>
+		<parameter>remotefile</parameter>
+		<parameter>localfile</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="ftpdownload" xreflabel="ftp_download procedure">
+	  <title>Ftp_download Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>ftp_download</function></funcdef>
+	    <paramdef><parameter>host</parameter>
+		<parameter>localfile</parameter>
+		<parameter>remotefile</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="ftpclose" xreflabel="ftp_close procedure">
+	  <title>Ftp_close Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>ftp_close</function></funcdef>
+	    <paramdef><parameter>host</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>host</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="tipdownload" xreflabel="tip_download procedure">
+	  <title>Tip_download Procedure</title>
+
+	  <para></para>
+
+          <funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>tip_download</function></funcdef>
+              <paramdef><parameter>spawnid</parameter>
+              <parameter>file</parameter></paramdef>
+           </funcprototype>
+            </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>
+       </sect4>
+    </sect3>
+
+    <sect3 id="targetprocs">
+      <title>Procedures For Target Boards</title>
+
+      <para></para>
+
+      <sect4 id="defaultlink" xreflabel="default_link procedure">
+        <title>Default_link Procedure</title>
+
+	<para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>default_link</function></funcdef>
+	    <paramdef><parameter>board</parameter>
+	    <parameter>objects</parameter>
+	    <parameter>destfile</parameter>
+	    <parameter>flags</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="defaulttargetassemble" xreflabel="default_target_assemble
+	procedure">
+	  <title>Default_target_assemble Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>default_target_assemble</function></funcdef>
+	    <paramdef><parameter>source</parameter>
+	    <parameter>destfile</parameter>
+	    <parameter>flags</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="defaulttargetcompile" xreflabel="default_target_compile
+	procedure">
+	  <title>default_target_compile Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>default_target_compile</function></funcdef>
+	    <paramdef><parameter>source</parameter>
+	    <parameter>destfile</parameter>
+	    <parameter>type</parameter>
+	    <parameter>options</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="popconfig" xreflabel="pop_config procedure">
+	  <title>Pop_config Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>pop_config</function></funcdef>
+	    <paramdef><parameter>type</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>type</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="prunewarnings" xreflabel="prune_warnings procedure">
+	  <title>Prune_warnings Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>prune_warnings</function></funcdef>
+	    <paramdef><parameter>text</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>text</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="pushbuild" xreflabel="push_build procedure">
+	  <title>Push_build Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>push_build</function></funcdef>
+	    <paramdef><parameter>name</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="pushconfig" xreflabel="push_config procedure">
+	  <title>push_config Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>push_config</function></funcdef>
+	    <paramdef><parameter>type</parameter>
+	    <parameter>name</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="reboottarget" xreflabel="reboot_target procedure">
+	  <title>Reboot_target Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>reboot_target</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 id="targetassemble" xreflabel="target_assemble procedure">
+	  <title>Target_assemble Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>target_assemble</function></funcdef>
+	    <paramdef><parameter>source destfile flags</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="targetcompile" xreflabel="target_compile procedure">
+	  <title>Target_compile Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>target_compile</function></funcdef>
+	    <paramdef><parameter>source</parameter>
+	    <parameter>destfile</parameter>
+	    <parameter>type</parameter>
+	    <parameter>options</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+	</sect3>
+
+	<sect3 id="targetdb" xreflabel="target database library file ">
+	  <title>Target Database Procedures</title>
+
+	  <sect4 id="boardinfo" xreflabel="board_info procedure">
+	    <title>Board_info Procedure</title>
+
+	    <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>board_info</function></funcdef>
+	    <paramdef><parameter>machine</parameter>
+	    <parameter>op</parameter>
+	    <parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="hostinfo" xreflabel="host_info procedure">
+	  <title>Host_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>host_info</function></funcdef>
+	    <paramdef><parameter>op</parameter>
+	    <parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="setboardinfo" xreflabel="set_board_info procedure">
+	  <title>Set_board_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>set_board_info</function></funcdef>
+	    <paramdef><parameter>entry</parameter>
+	    <parameter>value</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="setcurrtargetinfo" xreflabel="set_currtarget_info
+	procedure">
+	  <title>Set_currtarget_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>set_currtarget_info</function></funcdef>
+	    <paramdef><parameter>entry</parameter>
+	    <parameter>value</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="targetinfo" xreflabel="target_info procedure">
+	  <title>Target_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>target_info</function></funcdef>
+	    <paramdef><parameter>op</parameter>
+	    <parameter>args</parameter></paramdef>
+           </funcprototype>
+        </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>
+	</sect4>
+
+	<sect4 id="unsetboardinfo" xreflabel="unset_board_info procedure">
+	  <title>Unset_board_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>unset_board_info</function></funcdef>
+	    <paramdef><parameter>entry</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>entry</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="unsetcurrtargetinfo" xreflabel="unset_currtarget_info
+	procedure">
+	  <title>Unset_currtarget_info Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>unset_currtarget_info</function></funcdef>
+	    <paramdef><parameter>entry</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>entry</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>push_target</function></funcdef>
+	    <paramdef><parameter>name</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para>The name of the target to make current
+	    connection.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="poptarget" xreflabel="poptarget procedure">
+	  <title>Pop_target Procedure</title>
+
+	  <para>This unsets the current target connection.</para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>pop_target</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>list_targets</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>push_host</function></funcdef>
+	    <paramdef><parameter>name</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="pophost" xreflabel="pop_host procedure">
+	  <title>Pop_host Procedure</title>
+
+	  <para>This unsets the current host connection.</para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>pop_host</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+	 </funcsynopsis>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>compile</function></funcdef>
+	    <paramdef><parameter>file</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>archive</function></funcdef>
+	    <paramdef><parameter>file</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>ranlib</function></funcdef>
+	    <paramdef><parameter>file</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>file</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>execute_anywhere</function></funcdef>
+	    <paramdef><parameter>cmdline</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>cmdline</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+    </sect3>
+    <sect3 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 testsuite.</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>
+	
+      	<sect4 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">
+          <funcprototype>
+            <funcdef><function>${tool}_start</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>${tool}_load</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>${tool}_exit</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>${tool}_version</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+    </sect3>
+
+    <sect3 id="utilprocs">
+      <title>Utility Procedures</title>
+
+      <sect4 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">
+          <funcprototype>
+            <funcdef><function>getdirs</function></funcdef>
+	    <paramdef><parameter>rootdir</parameter>
+		<parameter>pattern</parameter></paramdef>
+           </funcprototype>
+	</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>
+	</sect4>
+
+      <sect4 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">
+          <funcprototype>
+            <funcdef><function>find</function></funcdef>
+	    <paramdef><parameter>rootdir</parameter>
+	    <parameter>pattern</parameter></paramdef>
+           </funcprototype>
+	</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>
+	</sect4>
+
+        <sect4 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">
+          <funcprototype>
+            <funcdef><function>which</function></funcdef>
+	    <paramdef><parameter>file</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>binary</parameter></term>
+	    <listitem><para>The executable program or shell script to look
+	    for.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+        <sect4 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>.)</para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>grep</function></funcdef>
+	    <paramdef><parameter>filename</parameter>
+	    <parameter>regexp</parameter>
+	    <parameter>--line</parameter></paramdef>
+           </funcprototype>
+	</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>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>prune</function></funcdef>
+	    <paramdef><parameter>list</parameter>
+  	    <parameter>pattern</parameter></paramdef>
+           </funcprototype>
+	</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>
+
+	</sect4>
+
+	<sect4 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 Windows if you have Cygwin or another Unix subsystem for Windows
+	  installed.</para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>slay</function></funcdef>
+	    <paramdef><parameter>name</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para>The name of the program to kill.</para></listitem>
+          </varlistentry>
+	</variablelist>
+
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>absolute</function></funcdef>
+	    <paramdef><parameter>path</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>path</parameter></term>
+	    <listitem><para>The path to convert.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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>.</para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>psource</function></funcdef>
+	    <paramdef><parameter>file</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>filename</parameter></term>
+	    <listitem><para>The filename to Tcl script to
+	    source.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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 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. The second is the
+	  pathname of the current testcase under consideration. This is used
+	  by tools like compilers where each testcase is a file.</para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>runtest_file_p</function></funcdef>
+	    <paramdef><parameter>runtests</parameter>
+	    <parameter>testcase</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>runtests</parameter></term>
+	    <listitem><para>The list of patterns to compare against.
+              </para></listitem>
+          </varlistentry>
+          <varlistentry>
+	    <term><parameter>testcase</parameter></term>
+	    <listitem><para>The test case filename.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>diff</function></funcdef>
+	    <paramdef><parameter>file_1</parameter>
+	    <parameter>file_2</parameter></paramdef>
+           </funcprototype>
+	</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>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>setenv</function></funcdef>
+	    <paramdef><parameter>var</parameter>
+   	    <parameter>val</parameter></paramdef>
+           </funcprototype>
+	 </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>
+
+        </sect4>
+	<sect4 id="unsetenv" xreflabel="unsetenv procedure">
+	  <title>unsetenv Procedure</title>
+
+	  <para>Unsets the environment variable
+	  <emphasis>var</emphasis>.</para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>unsetenv</function></funcdef>
+	    <paramdef><parameter>var</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para>The environment variable to
+	    unset.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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.</para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>getenv</function></funcdef>
+	    <paramdef><parameter>var</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para>The environment variable to get the value
+	    of.</para></listitem>
+          </varlistentry>
+	</variablelist>
+
+      </sect4>
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>prune_system_crud</function></funcdef>
+	    <paramdef><parameter>system</parameter>
+	    <parameter>test</parameter></paramdef>
+           </funcprototype>
+	</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>
+	</sect4>
+	
+    </sect3>
+
+    <sect3 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>
+
+      <sect4 id="libglosslinkflags" xreflabel="libgloss_link_flags procedure">
+        <title>Libgloss_link_flags Procedure</title>
+
+	<para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>libgloss_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="libglossincludeflags" xreflabel="libgloss_include_flags
+	procedure">
+	  <title>Libgloss_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>libgloss_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="newliblinkflags" xreflabel="newlib_link_flags procedure">
+	  <title>Newlib_link_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>newlib_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="newlibincludeflags" xreflabel="newlib_include_flags
+	procedure">
+	  <title>Newlib_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>newlib_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="libioincludeflags" xreflabel="libio_include_flags
+	procedure">
+	  <title>Libio_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>libio_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="libiolinkflags" xreflabel="libio_link_flags procedure">
+	  <title>Libio_link_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>libio_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="gxxincludeflags" xreflabel="g++_include_flags procedure">
+	  <title>G++_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>g++_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="gxxlinkflags" xreflabel="g++_link_flags procedure">
+	  <title>G++_link_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>g++_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="libstdcxxincludeflags" xreflabel="libstdc++_include_flags
+	procedure">
+	  <title>Libstdc++_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>libstdc++_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="libstdcxxlinkflags" xreflabel="libstdc++_link_flags
+	procedure">
+	  <title>Libstdc++_link_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>libstdc++_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="getmultilibs" xreflabel="get_multilibs procedure">
+	  <title>Get_multilibs Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>get_multilibs</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="findbinutilsprog" xreflabel="find_binutils_prog procedure">
+	  <title>Find_binutils_prog Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>find_binutils_prog</function></funcdef>
+	    <paramdef><parameter>name</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>name</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="findgcc" xreflabel="find_gcc procedure">
+	  <title>Find_gcc Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>find_gcc</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 id="findgcj" xreflabel="find_gcj procedure">
+	  <title>Find_gcj Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>find_gcj</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 id="findgxx" xreflabel="find_g++ procedure">
+	  <title>Find_g++ Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>find_g++</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 id="findg77" xreflabel="find_g77 procedure">
+	  <title>Find_g77 Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>find_g77</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 id="processmultiliboptions" xreflabel="process_multilib_options
+	procedure">
+	  <title>Process_multilib_options Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>process_multilib_options</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="addmultiliboption" xreflabel="add_multilib_option
+	procedure">
+	  <title>Add_multilib_option Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>add_multilib_option</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="findgas" xreflabel="find_gas procedure">
+	  <title>Find_gas Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>find_gas</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 id="findld" xreflabel="find_ld procedure">
+	  <title>Find_ld Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>find_ld</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect4>
+
+	<sect4 id="buildwrapper" xreflabel="build_wrapper procedure">
+	  <title>Build_wrapper Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>build_wrapper</function></funcdef>
+	    <paramdef><parameter>gluefile</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>gluefile</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="winsupincludeflags" xreflabel="winsup_include_flags
+	procedure">
+	  <title>Winsup_include_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>winsup_include_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="winsuplinkflags" xreflabel="winsup_link_flags procedure">
+	  <title>Winsup_link_flags Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>winsup_link_flags</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+    </sect3>
+
+    <sect3 id="debugprocs" xreflabel="Debugging Procedures">
+      <title>Procedures for debugging your Tcl code.</title>
+
+      <para><filename>lib/debugger.exp</filename>defines these utility
+      procedures:</para>
+
+      <sect4 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">
+          <funcprototype>
+            <funcdef><function>dumpvars</function></funcdef>
+	    <paramdef><parameter>vars</parameter></paramdef>
+           </funcprototype>
+	   </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>vars</parameter></term>
+	    <listitem><para>The variables to dump.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>dumplocals</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>dumprocs</function></funcdef>
+	    <paramdef><parameter>pattern</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>pattern</parameter></term>
+	    <listitem><para>The csh "glob" style pattern to look
+	    for.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>dumpwatch</function></funcdef>
+	    <paramdef><parameter>pattern</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>pattern</parameter></term>
+	    <listitem><para>The csh "glob" style pattern to look
+	    for.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="watcharray" xreflabel="watcharray procedure">
+	  <title>Watcharray Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+           <funcprototype>
+            <funcdef><function>watcharray</function></funcdef>
+	    <paramdef><parameter>element</parameter>
+		<parameter>type</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>type</parameter></term>
+	    <listitem><para>The csh "glob" style pattern to look
+	    for.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 id="watchvar" xreflabel="watchvar procedure">
+	  <title>Watchvar Procedure</title>
+
+	  <para></para>
+
+	<funcsynopsis role="tcl">
+          <funcprototype>
+            <funcdef><function>watchvar</function></funcdef>
+	    <paramdef><parameter>var</parameter>
+		<parameter>type</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>watchunset</function></funcdef>
+	    <paramdef><parameter>arg</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>watchwrite</function></funcdef>
+	    <paramdef><parameter>var</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para>The variable to watch.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>	
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>watchread</function></funcdef>
+	    <paramdef><parameter>var</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para>The variable to watch.</para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>watchdel</function></funcdef>
+	    <paramdef><parameter>args</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>args</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>print</function></funcdef>
+	    <paramdef><parameter>var</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter>var</parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+	<sect4 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">
+          <funcprototype>
+            <funcdef><function>quit</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	<variablelist>
+          <varlistentry>
+	    <term><parameter></parameter></term>
+	    <listitem><para></para></listitem>
+          </varlistentry>
+	</variablelist>
+	</sect4>
+
+    </sect3>
+
+  </sect2>
+
+   <sect2 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>
+      <listitem><para>lib/dejagnu.exp</para></listitem>
+    </itemizedlist>
+
+  </sect2>
+
+</sect1>
+
+<sect1 id="unittestapi" xreflabel="Unit Testing API">
+  <title>Unit Testing API</title>
+
+    <sect2 id="cunit" xreflabel="C Unit Testing API">
+    <title>C Unit Testing API</title>
+
+    <para>All of the functions that take a
+    <parameter>msg</parameter> parameter use a C char * that is
+    the message to be dislayed. There currently is no support for
+    variable length arguments.</para>
+
+
+    <sect3 id="passfunc" xreflabel="pass function">
+    <title>Pass Function</title>
+
+	  <para>This prints a message for a successful test
+	  completion.</para>
+
+	  <funcsynopsis role="C">
+          <funcprototype>
+	  <funcdef><function>pass</function></funcdef>
+	  <paramdef><parameter>msg</parameter></paramdef>
+           </funcprototype>
+	  </funcsynopsis>
+
+    </sect3>
+
+    <sect3 id="failfunc" xreflabel="fail function">
+    <title>Fail Function</title>
+
+	  <para>This prints a message for an unsuccessful test
+	  completion.</para>
+
+	  <funcsynopsis role="C">
+          <funcprototype>
+	  <funcdef><function>fail</function></funcdef>
+	  <paramdef><parameter>msg</parameter></paramdef>
+           </funcprototype>
+	  </funcsynopsis>
+
+    </sect3>
+
+	<sect3 id="untestedfunc" xreflabel="untested function">
+	  <title>Untested Function</title>
+
+	  <para>This prints a message for an test case that isn't run
+	  for some technical reason.</para>
+
+	<funcsynopsis role="C">
+          <funcprototype>
+            <funcdef><function>untested</function></funcdef>
+	    <paramdef><parameter>msg</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	</sect3>
+
+	<sect3 id="unresolvedfunc" xreflabel="unresolved function">
+	  <title>Unresolved Function</title>
+
+	  <para>This prints a message for an test case that is run,
+	  but there is no clear result. These output states require a
+	  human to look over the results to determine what happened.
+	  </para>
+
+	<funcsynopsis role="C">
+          <funcprototype>
+            <funcdef><function>unresolved</function></funcdef>
+	    <paramdef><parameter>msg</parameter></paramdef>
+           </funcprototype>
+	        </funcsynopsis>
+	</sect3>
+
+	<sect3 id="totalsfunc" xreflabel="totals function">
+	  <title>Totals Function</title>
+
+	  <para>This prints out the total numbers of all the test
+	  state outputs.</para>
+
+	<funcsynopsis role="C">
+          <funcprototype>
+            <funcdef><function>totals</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect3>
+
+    </sect2>
+
+    <sect2 id="cppunit" xreflabel="C++ Unit Testing API">
+	   <title>C++ Unit Testing API</title>
+
+	   <para>All of the methods that take a
+	   	  <parameter>msg</parameter> parameter use a C char *
+		  or STL string, that is the message to be
+	   	  dislayed. There currently is no support for variable
+	   	  length arguments.</para>
+
+	   <sect3 id="passmeth" xreflabel="pass method">
+	   <title>Pass Method</title>
+
+	  <para>This prints a message for a successful test
+	  completion.</para>
+
+	<funcsynopsis role="C++">
+          <funcprototype>
+            <funcdef><function>TestState::pass</function></funcdef>
+	    <paramdef><parameter>msg</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	</sect3>
+
+	<sect3 id="failmeth" xreflabel="fail method">
+	  <title>Fail Method</title>
+
+	  <para>This prints a message for an unsuccessful test
+	  completion.</para>
+
+	<funcsynopsis role="C++">
+          <funcprototype>
+            <funcdef><function>TestState::fail</function></funcdef>
+	    <paramdef><parameter>msg</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	</sect3>
+
+	<sect3 id="untestedmeth" xreflabel="untested method">
+	  <title>Untested Method</title>
+
+	  <para>This prints a message for an test case that isn't run
+	  for some technical reason.</para>
+
+	<funcsynopsis role="C++">
+          <funcprototype>
+            <funcdef><function>TestState::untested</function></funcdef>
+	    <paramdef><parameter>msg</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	</sect3>
+
+	<sect3 id="unresolvedmeth" xreflabel="unresolved method">
+	  <title>Unresolved Method</title>
+
+	  <para>This prints a message for an test case that is run,
+	  but there is no clear result. These output states require a
+	  human to look over the results to determine what happened.
+	  </para>
+
+	<funcsynopsis role="C++">
+          <funcprototype>
+            <funcdef><function>TestState::unresolved</function></funcdef>
+	    <paramdef><parameter>msg</parameter></paramdef>
+           </funcprototype>
+	</funcsynopsis>
+	</sect3>
+
+	<sect3 id="totalsmeth" xreflabel="totals method">
+	  <title>Totals Method</title>
+
+	  <para>This prints out the total numbers of all the test
+	  state outputs.</para>
+
+	<funcsynopsis role="C++">
+          <funcprototype>
+            <funcdef><function>TestState::totals</function></funcdef>
+	    <paramdef><parameter></parameter></paramdef>
+           </funcprototype>
+        </funcsynopsis>
+	</sect3>
+
+     </sect2>
+
+</sect1>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:nil
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/C/topic.dat b/doc/C/topic.dat
new file mode 100644
index 0000000..5291acd
--- /dev/null
+++ b/doc/C/topic.dat
@@ -0,0 +1 @@
+html/index.html   DejaGnu Manual
diff --git a/doc/C/user.xml b/doc/C/user.xml
new file mode 100644
index 0000000..f4fa81d
--- /dev/null
+++ b/doc/C/user.xml
@@ -0,0 +1,3181 @@
+
+ <sect1 id="gettingup">
+    <title>Getting DejaGnu up and running</title>
+
+<para>This chapter was originally written by Niklaus Giger
+ (ngiger@mus.ch) because he lost a week to figure out how DejaGnu works
+ and how to write a first test.
+</para> 
+
+<para>Follow these instructions as closely a possible in order get a
+good insight into how DejaGnu works, else you might run into a lot of
+subtle problems. You have been warned.</para> 
+
+<para>It should be no big problems installing DejaGnu using your
+package manager or from the source code. Under a Debian/GNU/Linux
+systems just type (as root) <programlisting>apt-get
+dejagnu</programlisting>. These examples were run on a primary machine
+with a AMD K6 and a Mac Powerbook G3 serving as a remote
+target.</para> 
+
+<para> The tests for Windows were run under Windows NT using the
+actual Cygwin version (1.3.x as of October 2001). It's target system
+was a PPC embedded system running vxWorks. 
+</para>
+
+<sect2>
+<title>Test your installation</title>
+
+<para>Create a new user called "dgt" (DejaGnuTest), which uses bash as
+it login shell. PS1 must be set to '\u:\w\$ ' in its ~/.bashrc. Login
+as this user, create an empty directory and change the working
+directory to it. e.g</para> 
+
+<programlisting>
+dgt:~$ mkdir ~/dejagnu.test
+dgt:~$ cd ~/dejagnu.test
+</programlisting>
+
+<para>Now you are ready to test DejaGnu's main program called
+runtest. The expecteted output is shown</para> 
+
+<example>
+<title>Runtest output in a empty directory
+</title>
+
+<programlisting>
+dgt:~/dejagnu.test$ runtest
+WARNING: Couldn't find the global config file.
+WARNING: No tool specified Test
+Run By dgt on Sun Nov 25 17:07:03 2001 Native configuration is i586-pc-linux-gnu
+=== tests ===
+Schedule of variations: unix
+Running target unix Using /usr/share/dejagnu/baseboards/unix.exp as board description file for target.
+Using /usr/share/dejagnu/config/unix.exp as generic interface file for target.
+ERROR: Couldn't find tool config file for unix.
+=== Summary ===</programlisting>
+
+<para>We will show you later how to get rid of all the WARNING- and
+ERROR-messages. The files testrun.sum and testrun.log have been
+created, which do not interest us at this point. Let's remove
+them.</para> 
+
+<programlisting>:~/dejagnu.test$ rm testrun.sum testrun.log
+</programlisting>
+</example>
+
+<sect3>
+<title>Windows</title>
+
+<para>On Windows systems DejaGnu is part of a port of a lot of Unix
+tools to the Windows OS, called Cygwin. Cygwin may be downloaded and
+installed from a mirror of http://www.cygwin.com/. All examples were
+also run on Windows NT. If nothing is said, you can assume that you
+should get the same output as on a Unix system.</para> 
+
+<para>You will need a telnet daemon if you want to use a Windows box
+as a remote target. There seems to be a freeware telnet daemon at
+http://www.fictional.net/.</para>
+</sect3>
+
+<sect3>
+<title>Getting the source code for the calc example</title>
+
+<para>If you are running a Debian distribution you can find the
+examples under /usr/share/doc/dejagnu/examples. These examples seem to
+be missing in Red Hat's RPM. In this case download the sources of
+DejaGnu and adjust the pathes to the DejaGnu examples
+accordingly.</para>
+</sect3>
+</sect2>
+
+<sect2>
+<title>Create a minimal project, e.g. calc</title>
+
+<para>In this section you will to start a small project,
+using the sample application calc, which is part of your DejaGnu
+distribution</para> 
+
+<sect3><title>A simple project without the GNU autotools</title>
+
+<para>The runtest program can be run standalone. All the
+autoconf/automake support is just cause those programs are commonly
+used for other GNU applications. The key to running runtest standalone
+is having the local site.exp file setup correctly, which automake
+does.</para> 
+
+<para>The generated site.exp should like like:</para>
+<programlisting>
+set tool calc
+set srcdir .
+set objdir /home/dgt/dejagnu.test
+</programlisting></sect3>
+
+<sect3>
+<title>Using autoconf/autoheader/automake</title>
+
+<para>We have to prepare some input file in order to run autocon and
+automake. There is book &quot;GNU autoconf, automake and
+libtool&quot; by Garry V. Vaughan, et al. NewRider, ISBN
+1-57870-190-2 which describes this process thoroughly.</para> 
+
+<para>From the calc example distributed with the DejaGnu documentation
+you should copy the program file itself (calc.c) and some additional
+files, which you might examine a little bit close to derive their
+meanings.</para> 
+
+<programlisting>
+dgt:~/dejagnu.test$ cp -r /usr/share/doc/dejagnu/examples/calc/\
+{configure.in,Makefile.am,calc.c,testsuite} .
+</programlisting>
+
+<para>In Makemake.am note the presence of the AUTOMAKE_OPTIONS = dejagnu. This option is needed.</para>
+
+<para>Run aclocal to generate aclocal.m4, which is a collection of
+macros needed by configure.in</para> 
+
+<programlisting>
+dgt:~/dejagnu.test$ aclocal
+</programlisting>
+
+<para>autoconf is another part of the auto-tools. Run it to generate
+configure based on information contained in configure.in.</para>
+
+<programlisting>
+dgt:~/dejagnu.test$ autoconf
+</programlisting>
+
+<para>autoheader is another part of the auto-tools.
+Run it to generate calc.h.in. </para>
+
+<programlisting>
+dgt:~/dejagnu.test$ autoheader
+</programlisting>
+
+<para>The Makefile.am of this example was developed as port of the DejaGnu
+distribution.
+Adapt Makefile.am for this test. Replace the line
+&quot;#noinst_PROGRAMS = calc&quot; to
+&quot;bin_PROGRAMS = calc&quot;.
+Change the RUNTESTDEFAULTFLAGS from
+&quot;$$srcdir/testsuite&quot; to
+&quot;./testsuite&quot;.</para>
+
+<para>Running automake at this point contains a series of warning in
+its output as shown in the following example:</para>
+
+<example>
+<title>Sample output of automake with missing files</title>
+<programlisting>
+dgt:~/dejagnu.test$ automake --add-missing
+automake: configure.in: installing `./install-sh'
+automake: configure.in: installing `./mkinstalldirs'
+automake: configure.in: installing `./missing'
+automake: Makefile.am: installing `./INSTALL'
+automake: Makefile.am: required file `./NEWS' not found
+automake: Makefile.am: required file `./README' not found
+automake: Makefile.am: installing `./COPYING'
+automake: Makefile.am: required file `./AUTHORS' not found
+automake: Makefile.am: required file `./ChangeLog' not found
+configure.in: 4: required file `./calc.h.in' not found
+Makefile.am:6: required directory ./doc does not exist
+</programlisting>
+</example>
+
+<para>Create a empty directory doc and empty files
+INSTALL, NEWS, README, AUTHORS, ChangeLog and COPYING.
+The default COPYING will point to the GNU Public License (GPL).
+In a real project it would be time to add some meaningfull text in each file.
+</para>
+
+<para>Adapt calc to your environment by calling configure.</para>
+<example>
+<title>Sample output of configure
+</title>
+<programlisting>
+dgt:~/dejagnu.test$ ./configure
+creating cache ./config.cache
+checking whether to enable maintainer-specific portions of Makefiles... no
+checking for a BSD compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+checking whether make sets ${MAKE}... yes
+checking for working aclocal... found
+checking for working autoconf... found
+checking for working automake... found
+checking for working autoheader... found
+checking for working makeinfo... found
+checking for gcc... gcc checking whether the C compiler (gcc ) works... yes
+checking whether the C compiler (gcc ) is a cross-compiler... no
+checking whether we are using GNU C... yes
+checking whether gcc accepts -g... yes
+checking for a BSD compatible install... /usr/bin/install -c
+checking how to run the C preprocessor... gcc -E
+checking for stdlib.h... yes
+checking for strcmp... yes
+updating cache ./config.cache
+creating ./config.status
+creating Makefile creating calc.h
+</programlisting>
+</example>
+
+<para>If you are familiar with GNU software,
+this output should not contain any surprise to you.
+Any errors should be easy to fix for such a simple program.</para>
+
+<para>Build the calc executable:</para>
+
+<example>
+<title>Sample output building calc
+</title>
+<programlisting>
+dgt:~/dejagnu.test$ make
+gcc -DHAVE_CONFIG_H -I. -I. -I. -g -O2 -c calc.c
+gcc -g -O2 -o calc calc.o
+</programlisting>
+</example>
+
+<para>You prepared a few files and then called some
+commands. Respecting the right order assures a automatic and correctly
+compiled calc program. The following example resumes the correct
+order.</para>
+
+<example>
+<title>Creating the calc program using the GNU autotools</title>
+<programlisting>
+dgt:~/dejagnu.test$ aclocal
+dgt:~/dejagnu.test$ autoconf
+dgt:~/dejagnu.test$ autoheader
+dgt:~/dejagnu.test$ automake --add-missing
+dgt:~/dejagnu.test$ ./configure
+dgt:~/dejagnu.test$ make
+
+</programlisting>
+</example>
+
+<para>Play with calc and verify whether it works correctly.
+A sample session might look like this:</para>
+
+<programlisting>
+dgt:~/dejagnu.test$ ./calc
+calc: version
+Version: 1.1
+calc:<emphasis> </emphasis>add 3 4
+7
+calc: multiply 3 4<emphasis> </emphasis>
+12
+calc: multiply 2 4<emphasis> </emphasis>
+12
+calc: quit
+
+</programlisting>
+
+<para>Look at the intentional bug that 2 times 4 equals 12.</para>
+
+<para>The tests run by DejaGnu need a file called site.exp,
+which is automatically generated if we call &quot;make
+site.exp&quot;. This was the purpose of the &quot;AUTOMAKE_OPTIONS =
+dejagnu&quot; in Makefile.am.</para>
+
+<example>
+<title>Sample output generating a site.exp</title>
+<programlisting>
+dgt: make site.exp
+dgt:~/dejagnu.test$ make site.exp
+Making a new site.exp file...
+</programlisting>
+</example>
+
+
+</sect3>
+</sect2>
+
+<sect2>
+<title>Our first automated tests</title>
+<sect3><title>Running the test for the calc example</title>
+
+<para>Now we are ready to call the automated tests </para>
+
+<example>
+<title>Sample output of runtest in a configured directory</title>
+
+<programlisting>
+dgt:~/dejagnu.test$ make check
+make check-DEJAGNU
+make[1]: Entering directory `/home/dgt/dejagnu.test' srcdir=`cd . &amp;&amp; pwd`; export srcdir; \
+EXPECT=expect; export EXPECT; \ runtest=runtest; \
+if /bin/sh -c "$runtest --version" > /dev/null 2>&amp;1; then \
+$runtest --tool calc CALC=`pwd`/calc --srcdir ./testsuite ; \
+else echo "WARNING: could not find \`runtest'" 1>&amp;2; :;\
+fi
+WARNING: Couldn't find the global config file.
+WARNING: Couldn't find tool init file
+Test Run By dgt on Sun Nov 25 21:42:21 2001
+Native configuration is i586-pc-linux-gnu
+
+       === calc tests ===
+
+Schedule of variations:
+   unix
+
+Running target unix
+Using /usr/share/dejagnu/baseboards/unix.exp as board description file for target.
+Using /usr/share/dejagnu/config/unix.exp as generic interface file for target.
+Using ./testsuite/config/unix.exp as tool-and-target-specific interface file.
+Running ./testsuite/calc.test/calc.exp ...
+FAIL: multiply2 (bad match)
+
+=== calc Summary ===
+
+# of expected passes 5
+# of unexpected failures 1
+/home/Dgt/dejagnu.test/calc version Version: 1.1
+make[1]: *** [check-DEJAGNU] Fehler 1
+make[1]: Leaving directory `/home/Dgt/dejagnu.test' make: *** [check-am] Fehler 2
+</programlisting>
+</example>
+
+<para>Did you see the  line &quot;FAIL:&quot;? The test cases for calc catch the bug in the calc.c file. Fix the error in calc.c later as the following examples assume a unchanged calc.c.</para>
+
+<para>Examine the output files calc.sum and calc.log. Try to
+understand the testcases written in
+~/dejagnu.test/testsuite/calc.test/calc.exp. To understand Expect you
+might take a look at the book &quot;Exploring Expect&quot;, which is
+an excellent resource for learning and using Expect. (Pub: O'Reilly,
+ISBN 1-56592-090-2) The book contains hundreds of examples and also
+includes a tutorial on Tcl. Exploring Expect is 602 pages
+long.</para>
+
+</sect3>
+
+
+<sect3><title>The various config files or how to avoid warnings</title>
+
+<para>DejaGnu may be customized by each user. It first searches for a
+file called ~/.dejagnurc. Create the file ~/.dejagnurc and insert the
+following line:</para>
+
+<programlisting>
+puts "I am ~/.dejagnurc"
+</programlisting>
+
+<para>Rerun make check. Test whether the output contains "I am ~/.dejagnurc".
+Create ~/my_dejagnu.exp and insert the following line:</para>
+
+<programlisting>
+puts "I am ~/my_dejagnu.exp"
+</programlisting>
+
+<para>In a Bash-Shell enter</para>
+
+<programlisting>
+dgt:~/dejagnu.test$ export DEJAGNU=~/my_dejagnu.exp
+</programlisting>
+
+<para>Run &quot;make check&quot; again. The output should not contain
+&quot;WARNING: Couldn't find the global config file.&quot;.
+Create the sub-directory lib. Create the file &quot;calc.exp&quot; in it and insert the following line:</para>
+
+<programlisting>
+puts "I am lib/calc.exp"
+</programlisting>
+
+<para>The last warning &quot;WARNING: Couldn't find tool init file&quot;
+should not be part of the output of make check.
+Create the directory ~/boards. Create the file ~/boards/standard.exp and insert the following line:</para>
+
+<programlisting>
+puts "I am boards/standard.exp"
+</programlisting>
+
+<para>If the variable DEJAGNU is still not empty then the (abbreviated) output of &quot;make check&quot; should look like this:</para>
+
+<example>
+<title>Sample output of runtest with the usual configuration files</title>
+<programlisting>
+dgt:~/dejagnu.test$ make check
+&lt;...&gt;
+fi
+I am ~/.dejagnurc
+I am ~/my_dejagnu.exp
+I am lib/calc.exp
+Test Run By dgt on Sun Nov 25 22:19:14 2001
+Native configuration is i586-pc-linux-gnu
+
+     === calc tests ===
+Using /home/Dgt/boards/standard.exp as standard board description\
+file for build.
+I am ~/boards/standard.exp
+Using /home/Dgt/boards/standard.exp as standard board description\
+ file for host.
+I am ~/boards/standard.exp
+
+Schedule of variations:
+  unix
+
+Running target unix
+Using /home/Dgt/boards/standard.exp as standard board description\
+ file for target.
+I am ~/boards/standard.exp
+Using /usr/share/dejagnu/baseboards/unix.exp as board description file\
+for target.
+&lt;...&gt;
+</programlisting>
+</example>
+
+<para>It is up to you to decide when and where to use any of the above
+mentioned config files for customizing.
+This chapters showed you where and in which order the different config
+files are run.</para>
+</sect3>
+
+<sect3>
+<title>When trouble strikes</title>
+
+<para>Calling runtest with the '-v'-flag shows you in even more details which files are searched in which order. Passing it several times gives more and more details. </para>
+<example>
+<title>Displaying details about runtest execution</title>
+<programlisting>
+runtest -v -v -v --tool calc CALC=`pwd`/calc --srcdir ./testsuite
+</programlisting>
+</example>
+
+<para>Calling runtest with the '--debug'-flag logs a lot of details to dbg.log where you can analyse it afterwards. </para>
+
+<para>In all test cases you can temporary adjust the verbosity of information by adding the following Tcl-command to any tcl file that gets loaded by
+dejagnu, for instance, ~/.dejagnurc:</para>
+
+<programlisting>
+set verbose 9
+</programlisting>
+
+</sect3>
+
+<sect3>
+<title>Testing &quot;Hello world&quot; locally</title>
+
+<para>This test checks, whether the built-in shell command &quot;echo Hello world&quot;
+ will really write &quot;Hello world&quot; on the console.
+Create the file ~/dejagnu.test/testsuite/calc.test/local_echo.exp.
+It should contain the following lines</para>
+
+<example>
+<title>A first (local) test case</title>
+<programlisting>
+set test "Local Hello World"
+send "echo Hello World"
+expect {
+   -re "Hello World"  { pass "$test" }
+}
+</programlisting>
+</example>
+
+<para>Run runtest again and verify the output &quot;calc.log&quot;</para>
+</sect3>
+</sect2>
+
+<sect2>
+<title>A first remote test</title>
+
+<para>Testing remote targets is a lot trickier especially if you are using an
+ embedded target
+which has no built in support for things like a compiler, ftp server or a Bash-shell.
+Before you can test calc on a remote target you have to acquire a few basics skills.</para>
+
+<sect3>
+<title>Setup telnet to your own host</title>
+<para>The easiest remote host is usually the host you are working on.
+In this example we will use telnet to login in your own workstation.
+For security reason you should never have a telnet deamon running on
+machine connected on the internet, as password and usernames are transmitted
+ in clear text.
+We assume you know how to setup your machine for a telnet daemon.</para>
+
+<para>Next try whether you may login in your own host by issuing the
+command &quot;telnet localhost.1&quot;. In order to be able to
+distinguish between a normal session an a telnet login add the following lines to /home/dgt/.bashrc.</para>
+
+<programlisting>
+if [ "$REMOTEHOST" ]
+then
+   PS1='remote:\w\$ '
+fi
+</programlisting>
+
+<para>Now on the machine a &quot;remote&quot; login looks like this:</para>
+
+<example>
+<title>Sample log of a telnet login to localhost</title>
+<programlisting>
+dgt:~/dejagnu.test$ telnet localhost
+Trying 127.0.0.1...
+Connected to 127.0.0.1.
+Escape character is '^]'.
+Debian GNU/Linux testing/unstable Linux
+K6Linux login: dgt
+Password:
+Last login: Sun Nov 25 22:46:34 2001 from localhost on pts/4
+Linux K6Linux 2.4.14 #1 Fre Nov 16 19:28:25 CET 2001 i586 unknown
+No mail.
+remote:~$ exit
+logout
+Connection closed by foreign host.
+</programlisting>
+</example>
+</sect3>
+
+<sect3>
+<title>A test case for login via telnet</title>
+<para>In order to define a correct setup we have add a line containing
+&quot;set target unix&quot; either to ~/.dejagnurc or to ~/my_dejagnu.exp.
+In ~/boards/standard.exp add the following four lines to define a few patterns for the DejaGnu telnet login procedure.</para>
+
+<example>
+<title>Defining a remote target board</title>
+<programlisting>
+set_board_info shell_prompt    "remote:"
+set_board_info telnet_username "dgt"
+set_board_info telnet_password "top_secret"
+set_board_info hostname        "localhost"
+
+</programlisting>
+</example>
+
+<para>As DejaGnu will be parsing the telnet session output for some well
+known pattern the output there are a lot of things that can go wrong.
+If you have any problems verify your setup:</para>
+<itemizedlist>
+
+<listitem>
+<para>Is <filename>/etc/motd</filename> empty?</para></listitem>
+
+<listitem>
+<para>Is <filename>/etc/issue.net</filename> empty?</para></listitem>
+
+<listitem>
+<para>Exists a empty <filename>~/.hushlogin</filename>?</para></listitem>
+
+<listitem>
+<para>The LANG environment variable must be either empty or set to &quot;C&quot;. </para></listitem>
+
+</itemizedlist>
+<para>To test the login via telnet write a sample test case.
+Create the file ~/dejagnu.test/testsuite/calc.test/remote_echo.exp and
+add the following few lines:</para>
+
+<example>
+<title>DejaGnu script for logging in into a remote target</title>
+<programlisting>
+puts "this is remote_echo.exp target for $target "
+target_info $target
+#set verbose 9
+set shell_id [remote_open $target]
+set test "Remote login to $target"
+#set verbose 0
+puts "Spawn id for remote shell is $shell_id"
+if { $shell_id > 0 } {
+   pass "$test"
+} else {
+   fail "Remote open to $target"
+}
+</programlisting>
+</example>
+
+<para>In the runtest output you should find something like:</para>
+
+<programlisting>
+Running ./testsuite/calc.test/local_echo.exp ...
+Running ./testsuite/calc.test/remote_echoo.exp ...
+this is remote_echo.exp target is unix
+Spawn id for remote shell is exp7
+</programlisting>
+
+<para>Have again a look at calc.log to get a feeling how DejaGnu and expect
+parse the input. </para></sect3>
+
+<sect3>
+<title>Remote testing &quot;Hello world&quot;</title>
+
+<para>Next you will transform the above &quot;hello world&quot; example to
+its remote equivalent.
+This can be done by adding the following lines to our file remote_echo.exp.</para>
+
+<example>
+<title>A first (local) remote "Hello world" test</title>
+<programlisting>
+set test "Remote_send Hello World"
+set status [remote_send $target "echo \"Hello\" \"World\"\n" ]
+pass "$test"
+set test "Remote_expect Hello World"
+remote_expect $target 5 {
+   -re "Hello World"  { pass "$test" }
+}
+</programlisting>
+</example>
+
+<para>Call make check. The output should contain
+&quot;# of expected passes 9&quot; and &quot;# of unexcpected failures 1&quot;.</para>
+
+<para>Have a look at the procedures in /usr/share/dejagnu/remote.exp to have an overview of the offered procedures and their features. </para>
+
+<para>Now setup a real target.
+In the following example we assume as target a PowerBook running Debian.
+As above add a test user "dgt", install telnet and FTP servers.
+In order to distinguish it from the host add the line
+<programlisting>PS1='test:>'</programlisting> to /home/dgt/.bash_profile.
+Also add a corresponding entry "powerbook" to /etc/hosts and verify that you
+are able to ping, telnet and ftp to the target "powerbook".</para>
+
+<para>In order to let runtest run its test on the "powerbook" target change the following lines in ~/boards/standard.exp:</para>
+
+<example>
+<title>Board definition for a remote target</title>
+<programlisting>
+set_board_info protocol        "telnet"
+set_board_info telnet_username "dgt"
+set_board_info telnet_password "top_secret"
+set_board_info shell_prompt    "test:> "
+set_board_info hostname        "powerbook"
+</programlisting>
+</example>
+
+<para>Now call runtest again with the same arguments and verify whether all went okay by taking a close look at calc.log.</para>
+</sect3>
+
+
+<sect3>
+<title>Transferring files from/to the target</title>
+
+<para>A simple procedure like this will do the job for you:</para>
+
+<example>
+<title>Test script to transfer a file to a remote target</title>
+<programlisting>
+set test "Remote_download"
+puts "Running Remote_download"
+# set verbose 9
+set remfile /home/dgt/dejagnu2
+
+set status [remote_download $target /home/dgt/.dejagnurc $remfile]
+if { "$status" == "" } {
+     fail "Remote download to $remfile on $target"
+} else {
+   pass "$test"
+}
+
+puts "status of remote_download ist $status"
+# set verbose 0
+</programlisting>
+</example>
+
+<para>After running runtest again, check whether the file dejagnu2 exists on the target.
+
+This example will only work if the rcp command works with your target.
+
+If you have a working FTP-server on the target you can use it by adding the
+following lines to ~/boards/standard.exp:</para>
+
+<example>
+<title>Defining a board to use FTP as file transport</title>
+<programlisting>
+set_board_info file_transfer   "ftp"
+set_board_info ftp_username    "dgt"
+set_board_info ftp_password    "1234"
+</programlisting>
+</example>
+
+</sect3>
+
+<sect3>
+<title>Preparing for crosscompilation</title>
+
+<para>For crosscompiling you need working binutils, gcc and a base library like
+libc or glib for your target.
+It is beyond the scope of this document to describe how to get it working.
+The following examples assume a cross compiler for PowerPC which is called linux-powerpc-gcc.
+</para>
+
+<para>Add AC_CANONICAL_TARGET in dejagnu.test/configure.in at the following location. Copy config.guess from /usr/share/automake to dejagnu.test.</para>
+
+<programlisting>
+AM_CONFIG_HEADER(calc.h)
+AC_CANONICAL_TARGET([])
+AM_INIT_AUTOMAKE(calc, 1.1)
+</programlisting>
+
+<para>You need to run automake 2.5 or later.
+Depending on your installation calling autoconf2.5 instead of autoconf is not needed.
+The sequence to regenerate all files is:</para>
+
+<example>
+<title>Using autotools for cross development</title>
+<programlisting>
+$ autoconf2.5
+$ autoheader
+$ automake
+$ ./configure --host=powerpc-linux --target=powerpc-linux
+configure: WARNING: If you wanted to set the --build type, don't use --host.
+    If a cross compiler is detected then cross compile mode will be used.
+checking build system type... ./config.guess: ./config.guess: No such file or directory
+configure: error: cannot guess build type; you must specify one
+$ cp /usr/share/automake/config.guess .
+$ ./configure --host=powerpc-linux --target=powerpc-linux
+configure: WARNING: If you wanted to set the --build type, don't use --host.
+If a cross compiler is detected then cross compile mode will be used. \
+checking build system type... i586-pc-linux-gnu
+checking host system type... powerpc-unknown-linux-gnu
+&lt;...&gt;
+checking whether we are cross compiling... yes
+&lt;...&gt;
+Configuration:
+Source code location: .
+C Compiler: powerpc-linux-gcc
+C Compiler flags: -g -O2
+
+</programlisting>
+</example>
+
+<para>Everything should be ready to recompile for the target:</para>
+
+<programlisting>$ make
+powerpc-linux-gcc -DHAVE_CONFIG_H -I. -I. -I. -g -O2 -c calc.c
+powerpc-linux-gcc -g -O2 -o calc calc.o
+
+</programlisting>
+</sect3>
+
+<sect3>
+<title>Remote testing of calc</title>
+<para>Not yet written, as I have problem getting libc6-dev-powerpc to work. Probably I first have to build my cross compiler. </para>
+</sect3>
+
+<sect3>
+<title>Using Windows as host and vxWorks as target</title>
+
+<para>A more thorough walk-through will be written in a few weeks.</para>
+
+<para>In order to test the vxWorks as a target I changed boards/standards.exp to reflect my settings (IP, username, password). Then I reconfigured vxWorks to include a FTP and telnet server (using the same username/password combination ad in boards/standard.exp).</para>
+
+<para>With this setup and some minor modification (e.g. replacing echo by printf) in my test cases I could test my vxWorks system. It sure does not seem to be a correct setup by DejaGnu standard. For instance, it still loading /usr/share/dejagnu/baseboards/unix.exp instead of vxWorks. In any case I found that (at least under Windows) I did not find out how the command line would let me override settings in my personal config files.</para>
+
+</sect3>
+</sect2>
+</sect1>
+ <sect1 id="runningtests">
+    <title>Running Tests</title>
+
+    <para>There are two ways to execute a testsuite. 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>
+
+    <sect2 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>
+
+    </sect2>
+
+    <sect2 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>
+
+      <sect3 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
+          testsuite 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
+          testsuites 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>
+
+    </sect3>
+
+    <sect3 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 testsuite 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>
+    </sect3>
+
+       <sect3 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 testsuite 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>
+
+	<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>.)</para>
+      </sect3>
+    </sect2>
+
+    <sect2 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>
+
+    <sect3 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>
+
+      <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>
+
+    </sect3>
+
+    <sect3 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>
+
+    </sect3>
+
+    <sect3 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>
+    </sect3>
+   </sect2>
+  </sect1>
+
+  <sect1 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 testsuite 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 testsuite 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 testsuite 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>
+
+    <sect2 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 testsuite.</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, i.e., 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 "-isystem /build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -isystem $srcdir/../libg++/src -isystem $srcdir/../libio -isystem $srcdir/../libstdc++ -isystem $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 testsuite. 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>
+
+    </sect2>
+     <sect2 id="global" xreflabel="Global Config File">
+      <title>Global Config File</title>
+
+      <para>The master config file is where all the target specific
+      config variables 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>
+
+    </sect2>
+
+    <sect2 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> &amp;
+     <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> &amp;
+     <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>
+
+    </sect2>
+
+    <sect2 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/Windows 3.1, MacOS and Windows.</para>
+
+      <para>The recommended source for a Windows-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 Windows, 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:</para>
+
+      <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>&amp;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>
+
+    </sect2>
+
+    <sect2 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>
+
+      <sect3 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>
+
+	  <row>
+	    <entry>--mail</entry>
+	    <entry>address</entry>
+	    <entry>Email the output log to the specified address.</entry>
+	  </row>
+
+	  </tbody>
+	  </tgroup>
+	  </table>
+	</para>
+
+    </sect3>
+
+    <sect3 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>
+
+      </sect3>
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="Extending" xreflabel="Extending DejaGnu">
+    <title>Extending DejaGnu</title>
+
+    <sect2 id="addsuite"  xreflabel="Adding a new Testsuite">
+      <title>Adding A New Testsuite</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>
+
+    </sect2>
+
+    <sect2 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 testsuites.  Unfortunately, well-established testsuites 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 testsuites may make the prospect of
+      creating an entirely new testsuite appear overwhelming.  Nevertheless,
+      it is quite straightforward to get a new testsuite going.</para>
+
+      <para>There is one testsuite 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
+      testsuite for it.  Reading this testsuite, and experimenting with it,
+      is a good way to supplement the information in this section.  (Thanks to
+      Robert Lupton for creating calc and its testsuite---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 testsuite 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 &lt; 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>
+
+    </sect2>
+
+    <sect2 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>
+
+    </sect2>
+
+    <sect2 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>
+
+    </sect2>
+
+    <sect2 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 &amp; 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>
+
+    </sect2>
+
+    <sect2 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>
+
+    </sect2>
+
+    <sect2 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>
+
+      <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>
+
+       <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></listitem>
+       </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="adding" xreflabel="Adding A Test Case To A Testsuite">
+      <title>Adding A Test Case To A Testsuite.</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 testsuite
+      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>
+
+      <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>
+
+    </sect2>
+
+    <sect2 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>&quot;</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>
+
+    </sect2>
+
+    <sect2 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>
+
+    </sect2>
+
+</sect1>
+
+  <sect1 id="unit" xreflabel="Unit Testing">
+    <title>Unit Testing</title>
+
+    <sect2 id="unittest"  xreflabel="What Is Unit Testing ?">
+      <title>What Is Unit Testing ?</title>
+
+      <para>Most regression testing as done by DejaGnu is system
+      testing. This is the complete application is tested all at
+      once. Unit testing is for testing single files, or small
+      libraries. In this case, each file is linked with a test case in
+      C or C++, and each function or class and method is tested in
+      series, with the test case having to check private data or
+      global variables to see if the function or method worked.</para>
+
+      <para>This works particularly well for testing APIs and at level
+      where it is easier to debug them, than by needing to trace through
+      the entire appication. Also if there is a specification for the
+      API to be tested, the testcase can also function as a compliance
+      test.</para>
+
+    </sect2>
+
+    <sect2 id="djh" xreflabel="The dejagnu.h Header File">
+      <title>The dejagnu.h Header File</title>
+
+      <para>DejaGnu uses a single header file to assist in unit
+      testing. As this file also produces it's one test state output,
+      it can be run standalone, which is very useful for testing on
+      embedded systems. This header file has a C and C++ API for the
+      test states, with simple totals, and standardized
+      output. Because the output has been standardized, DejaGnu can be
+      made to work with this test case, without writing almost any
+      Tcl. The library module, dejagnu.exp, will look for the output
+      messages, and then merge them into DejaGnu's.</para>
+
+     </sect2>
+
+</sect1>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:nil
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->