guide.html: run_doxygen uses bash.

2003-08-04  Phil Edwards  <pme@gcc.gnu.org>

	* docs/doxygen/guide.html:  run_doxygen uses bash.
	* docs/doxygen/mainpage.html:  We'll be shipping tag files.
	* docs/doxygen/run_doxygen:  Tweaks and improvements.
	* docs/doxygen/user.cfg.in:  Set GENERATE_TAGFILE.
	* docs/html/install.html:  Update autoconf/automake requirements.
	* docs/html/test.html:  Add section describing DejaGNU support.
	* docs/html/17_intro/confdeps.dot:  New file, generates...
	* docs/html/17_intro/confdeps.png:  ...this new file.
	* docs/html/Makefile:  Generated here.
	* docs/html/17_intro/configury.html:  New file.

From-SVN: r70164

libstdc++-v3/ChangeLog

+2003-08-04  Phil Edwards  <pme@gcc.gnu.org>
+
+	* docs/doxygen/guide.html:  run_doxygen uses bash.
+	* docs/doxygen/mainpage.html:  We'll be shipping tag files.
+	* docs/doxygen/run_doxygen:  Tweaks and improvements.
+	* docs/doxygen/user.cfg.in:  Set GENERATE_TAGFILE.
+	* docs/html/install.html:  Update autoconf/automake requirements.
+	* docs/html/test.html:  Add section describing DejaGNU support.
+	* docs/html/17_intro/confdeps.dot:  New file, generates...
+	* docs/html/17_intro/confdeps.png:  ...this new file.
+	* docs/html/Makefile:  Generated here.
+	* docs/html/17_intro/configury.html:  New file.
+
 2003-07-31  Phil Edwards  <pme@gcc.gnu.org>
 
 	* testsuite/lib/libstdc++-v3-dg.exp:  Rename...

libstdc++-v3/docs/doxygen/guide.html

@@ -28,7 +28,7 @@
    <code>'make doxygen-maint'</code>, and <code>'make doxygen-man'</code>
    in the libstdc++-v3 build directory generate the user-level HTML docs, the
    maintainer-level HTML docs, and the man pages, respectively.  Prerequisite
-   tools are
+   tools are Bash 2.x, 
    <a href="http://www.doxygen.org/">
    <!-- snagged from the generated page -->
    <img src="doxygen.png" alt="Doxygen" align=center border=0 width=110 height=53>

libstdc++-v3/docs/doxygen/mainpage.html

@@ -58,6 +58,19 @@
    </ul>
 </p>
 
+<p>If you are using Doxygen for your own projects, you can use
+   <a href="libstdc++.tag">a tag file for the appropriate version</a> and
+   an entry such as
+   <blockquote>
+   TAGFILES = "libstdc++.tag = 
+   http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen"
+   </blockquote>
+   Be sure to adjust the URL for the right version.  If you download a
+   local copy of the source documentation for faster viewing, you can use
+   the doxytag/installdox programs (part of Doxygen) to adjust the links
+   for you.
+</p>
+
 <h2>Generating the documentation</h2>
 <p>These HTML pages are automatically generated, along with the man pages.
    See <code>docs/doxygen/guide.html</code> in the source tree for how to

libstdc++-v3/docs/doxygen/run_doxygen

-#!/bin/sh
+#!/bin/bash
 
 # Runs doxygen and massages the output files.
 # Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc.
@@ -10,12 +10,11 @@
 
 # We can check now that the version of doxygen is >= this variable.
 DOXYVER=1.2.15
-doxygen=
 
 find_doxygen() {
-    v_required=`echo $DOXYVER |  \
+    local -r v_required=`echo $DOXYVER |  \
                 awk -F. '{if(NF<3)$3=0;print ($1*100+$2)*100+$3}'`
-    testing_version=
+    local testing_version doxygen maybedoxy v_found
     # thank you goat book
     set `IFS=:; X="$PATH:/usr/local/bin:/bin:/usr/bin"; echo $X`
     for dir
@@ -36,6 +35,10 @@ find_doxygen() {
         echo run_doxygen error:  Could not find Doxygen $DOXYVER in path. 1>&2
         print_usage
     fi
+    # We need to use other tools from the same package/version.
+    echo :: Using Doxygen tools from ${dir}.
+    PATH=$dir:$PATH
+    hash -r
 }
 
 print_usage() {
@@ -142,8 +145,8 @@ test $do_man = yes && {
       -e "s=@do_man@=${do_man}=" \
       ${srcdir}/docs/doxygen/user.cfg.in > ${outdir}/${mode}.cfg
   echo :: NOTE that this may take some time...
-  echo $doxygen ${outdir}/${mode}.cfg
-  $doxygen ${outdir}/${mode}.cfg
+  echo doxygen ${outdir}/${mode}.cfg
+  doxygen ${outdir}/${mode}.cfg
   echo :: Finished, exit code was $?
 )
 ret=$?
@@ -151,6 +154,9 @@ test $ret -ne 0 && exit $ret
 
 test $do_html = yes && {
   cd ${outdir}/html_${mode}
+
+  #doxytag -t libstdc++.tag . > /dev/null 2>&1
+
   sed -e "s=@LEVEL@=${LEVELtext}=" \
       -e "s=@DATE@=${DATEtext}=" \
       ${srcdir}/docs/doxygen/mainpage.html > index.html

libstdc++-v3/docs/doxygen/user.cfg.in

@@ -902,7 +902,7 @@ TAGFILES               =
 # When a file name is specified after GENERATE_TAGFILE, doxygen will create 
 # a tag file that is based on the input files it reads.
 
-GENERATE_TAGFILE       = 
+GENERATE_TAGFILE       = @outdir@/@html_output_dir@/libstdc++.tag
 
 # If the ALLEXTERNALS tag is set to YES all external classes will be listed 
 # in the class index. If set to NO only the inherited external classes 

libstdc++-v3/docs/html/17_intro/confdeps.dot

+# Blatantly ripped out of the graphviz examples and modified.  -pme
+digraph v3conf {
+    size="6,6";
+    node [color=lightblue2, style=filled];
+    "aclocal.m4" -> "acinclude.m4";
+    "configure" -> "aclocal.m4";
+    "configure" -> "configure.ac";
+    "configure" -> "crossconfig.m4";
+    "configure" -> "linkage.m4";
+    "[*/]Makefile.in" -> "Makefile.am";
+    "[*/]Makefile.in" -> "configure.ac";
+    "config.h.in" -> "acconfig.h";
+    "config.h.in" -> "configure.ac";
+}

libstdc++-v3/docs/html/Makefile

@@ -5,6 +5,7 @@ INC=../../../gcc/doc/include
 
 all: documentation.html                  \
      faq/index.txt                       \
+     17_intro/confdeps.png               \
      17_intro/porting.html               \
      17_intro/porting-howto.html
 
@@ -34,4 +35,7 @@ faq/index.txt: faq/index.html
 17_intro/porting-howto.html: 17_intro/porting-howto.xml
 	xltproc -o $@ /usr/share/xml/docbook/xsl-stylesheets-1.48-2/html/docbook.xsl $<
 
+17_intro/confdeps.png: 17_intro/confdeps.dot
+	dot -Tpng -o $@ $<
+
 # vim:noet ts=4

libstdc++-v3/docs/html/install.html

@@ -57,10 +57,10 @@
 
    <p>In addition, if you plan to modify the makefiles or regenerate the
       configure scripts you'll need recent versions of the GNU Autotools:
-      autoconf (version 2.50 or later),
-      automake (version 1.4 or later),    <!-- special version? -->
-      and libtool (multilanguage, version 1.4 or later),  <!-- really? -->
-      in order to rebuild the files.
+      autoconf (version 2.57 or later) and
+      automake (version 1.7.6 or later),
+      in order to rebuild the files.  Libtool is built from special sources
+      in the GCC source tree.
       These tools are all required to be installed in the same location
       (most linux distributions install these tools by default, so no
       worries as long as the versions are correct).

libstdc++-v3/docs/html/test.html

@@ -35,6 +35,7 @@
    <li><a href="#new">How to write a new test case</a></li>
    <li><a href="#check">Options for running the tests</a></li>
    <li><a href="#future">Future</a></li>
+   <li><a href="#internals">DejaGNU internals</a></li>
 </ul>
 
 <hr />
@@ -79,13 +80,13 @@ thread		  Tests for threads.
    
    <p>
       Some directories don't have test files, but instead contain
-      auxiliary information:
+      auxiliary information (<a href="#internals">more information</a>):
    </p>
 
    <pre>
 config		  Files for the dejagnu test harness.
 lib		  Files for the dejagnu test harness.
-libstdc++-v3.dg	  Files for the dejagnu test harness.
+libstdc++*     	  Files for the dejagnu test harness.
 data		  Sample text files for testing input and output.
    </pre>
 
@@ -218,7 +219,7 @@ cat 27_io/objects/char/3_xin.in | a.out
         Used to check correctness of symbol versioning, visibility of
         exported symbols, and compatibility on symbols in the shared
         library, for hosts that support this feature. More information
-	can be found in the ABI documentation <a href="abi.txt"> here</a>
+        can be found in the ABI documentation <a href="abi.txt"> here</a>
        </p>
      </li>
      <li>
@@ -260,7 +261,7 @@ cat 27_io/objects/char/3_xin.in | a.out
          <li>time_counter</li>
          <li>resource_counter</li>
          <li>report_performance</li>
-      </ul>	
+      </ul>
        <p></p> 
      </li>
      <li>
@@ -585,6 +586,45 @@ Currently plans for supported keywords include:
 </dd>
 </dl>
 
+<hr />
+<h2><a name="internals">DejaGNU internals</a></h2>
+
+<p>This is information for those looking at making changes to the testsuite
+structure, and/or needing to trace dejagnu's actions with --verbose.  This
+will not be useful to people who are "merely" adding new tests to the existing
+structure.
+</p>
+
+<p>The first key point when working with dejagnu is the idea of a "tool".
+Files, directories, and functions are all implicitly used when they are
+named after the tool in use.  Here, the tool will always be "libstdc++".
+</p>
+
+<p>The <code>lib</code> subdir contains support routines.  The
+<code>lib/libstdc++.exp</code> file ("support library") is loaded
+automagically, and must explicitly load the others.  For example, files can
+be copied from the core compiler's support directory into <code>lib</code>.
+</p>
+
+<p>Some routines in <code>lib/libstdc++.exp</code> are callbacks, some are
+our own.  Callbacks must be prefixed with the name of the tool.  To easily
+distinguish the others, by convention our own routines are named "v3-*".
+</p>
+
+<p>The next key point when working with dejagnu is "test files".  Any
+directory whose name starts with the tool name will be searched for test files.
+(We have only one.)  In those directories, any <code>.exp</code> file is
+considered a test file, and will be run in turn.  Our main test file is called
+<code>normal.exp</code>; it runs all the tests in testsuite_files using the
+callbacks loaded from the support library.
+</p>
+
+<p>The <code>config</code> directory is searched for any particular "target
+board" information unique to this library.  This is currently unused and sets
+only default variables.
+</p>
+
+
 <!-- ####################################################### -->
 
 <hr />