acinclude.m4: Minor comment tweaks.

2002-08-31  Phil Edwards  <pme@gcc.gnu.org>

	* acinclude.m4:  Minor comment tweaks.

	* docs/html/makedoc.awk:  New file...
	* docs/html/Makefile:  ...called from here...
	* docs/html/documentation.html:  ...to help generate this.

	* docs/html/21_strings/howto.html:  Prepare for new entry.
	* include/bits/basic_string.h:  Initial basic_stirng hook for
	doxygen.  Remove trailing whitespace.
	* include/bits/char_traits.h:  Point to onlinedocs for new entry.
	* include/bits/stringfwd.h:  Add doxygen hooks for string and
	wstring typedefs.

From-SVN: r56711

libstdc++-v3/ChangeLog

+2002-08-31  Phil Edwards  <pme@gcc.gnu.org>
+
+	* acinclude.m4:  Minor comment tweaks.
+
+	* docs/html/makedoc.awk:  New file...
+	* docs/html/Makefile:  ...called from here...
+	* docs/html/documentation.html:  ...to help generate this.
+
+	* docs/html/21_strings/howto.html:  Prepare for new entry.
+	* include/bits/basic_string.h:  Initial basic_stirng hook for
+	doxygen.  Remove trailing whitespace.
+	* include/bits/char_traits.h:  Point to onlinedocs for new entry.
+	* include/bits/stringfwd.h:  Add doxygen hooks for string and
+	wstring typedefs.
+
 2002-08-29  Richard Earnshaw  <rearnshaw@arm.com>
 
 	* config/cpu/arm/cpu_limits.h: New file.

libstdc++-v3/acinclude.m4

 dnl
-dnl Initialize configure bits.
+dnl Initialize basic configure bits, set toplevel_srcdir for Makefiles.
 dnl
 dnl GLIBCPP_TOPREL_CONFIGURE
 AC_DEFUN(GLIBCPP_TOPREL_CONFIGURE, [
@@ -37,13 +37,10 @@ AC_DEFUN(GLIBCPP_TOPREL_CONFIGURE, [
 ])
 
 dnl
-dnl Initialize configure bits.
+dnl Initialize the rest of the library configury.
 dnl
 dnl GLIBCPP_CONFIGURE
 AC_DEFUN(GLIBCPP_CONFIGURE, [
-
-#possibly test for the presence of the compiler sources here?
-
   # Export build and source directories.
   # These need to be absolute paths, yet at the same time need to
   # canonicalize only relative paths, because then amd will not unmount

libstdc++-v3/docs/html/21_strings/howto.html

@@ -25,6 +25,7 @@
    <li><a href="#2">A case-insensitive string class</a>
    <li><a href="#3">Breaking a C++ string into tokens</a>
    <li><a href="#4">Simple transformations</a>
+   <li><a href="#5">Making strings of arbitrary character types</a>
 </ul>
 
 <hr>
@@ -321,6 +322,15 @@
       <a href="../faq/index.html">to the FAQ</a>.
    </p>
 
+<hr>
+<h2><a name="5">Making strings of arbitrary character types</a></h2>
+   <p>how to work with char_traits -- in the archives, just need to
+      go through and pull the examples together
+   </p>
+   <p>Return <a href="#top">to top of page</a> or
+      <a href="../faq/index.html">to the FAQ</a>.
+   </p>
+
 
 
 <!-- ####################################################### -->

libstdc++-v3/docs/html/Makefile

-PWD=$${PWDCMD-pwd}
 
+PWD=$${PWDCMD-pwd}
 MAKEINFO=makeinfo
 INC=../../../gcc/doc/include
 
-all: faq/index.txt 17_intro/porting.html 17_intro/porting-howto.html
+all: documentation.html                  \
+     faq/index.txt                       \
+     17_intro/porting.html               \
+     17_intro/porting-howto.html
 
+# chock full of GNUism, probably
+documentation.html: $(wildcard */howto.html)
+	sed -n '1,/beginlist/p' $@ > tmp.top
+	sed -n '/endlist/,$$p' $@ > tmp.bottom
+	echo '  <ul>' > tmp.middle
+	for i in [[:digit:]]*/howto.html; do \
+	  title=`grep 'h1 ' $$i |\
+	  sed 's=.*\(Chapter [[:digit:]]*\):[[:space:]]*\(.*\)</a>.*=\2 (\1)='` ;\
+	  awk -v file=$$i -v "title=$$title" -f makedoc.awk $$i >> tmp.middle ;\
+	done
+	awk -v file=ext/howto.html -v "title=Extensions to the Standard Library"\
+	  -f makedoc.awk ext/howto.html >> tmp.middle ;\
+	echo '  </ul>' >> tmp.middle
+	cat tmp.top tmp.middle tmp.bottom > $@
+	rm tmp.top tmp.middle tmp.bottom
 
 faq/index.txt: faq/index.html
 	lynx -dump $< | sed "s%file://localhost`${PWD}`%..%" > $@
@@ -16,3 +34,4 @@ 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 $<
 
+# vim:noet ts=4

libstdc++-v3/docs/html/makedoc.awk

+# Take apart bits of HTML and puts them back together again in new and
+# fascinating ways.  Copyright (C) 2002 Free Software Foundation, Inc.
+# Contributed by Phil Edwards <pme@gcc.gnu.org>.  Simple two-state automaton
+# inspired by Richard Henderson's gcc/mkmap-symver.awk.
+
+# 'file' is the name of the file on stdin
+# 'title' is the text to print at the start of the list
+
+BEGIN {
+  state = "looking";
+  entries = 0;
+  printf ("   <li>%s</li>\n", title);
+  printf ("   <ul>\n");
+}
+
+# Searching for the little table of contents at the top.
+state == "looking" && /^<h1>Contents/ {
+  state = "entries";
+  next;
+}
+
+# Ignore everything else up to that point.
+state == "looking" {
+  next;
+}
+
+# An entry in the table of contents.  Pull that line apart.
+state == "entries" && /<li>/ {
+  extract_info($0);
+  next;
+}
+
+# End of the list.  Don't bother reading the rest of the file.  (It could
+# also contain more <li>'s, so that would be incorrect as well as wasteful.)
+state == "entries" && /^<\/ul>/ {
+  exit;
+}
+
+END {
+  for (i = 0; i < entries; i++)
+    printf ("     %s\n", entry[i]);
+  printf ("   </ul>\n\n");
+}
+
+function extract_info(line) {
+  # thistarget will be things like "#5" or "elsewhere.html"
+  match(line,"href=\".*\"");
+  thistarget = substr(line,RSTART+6,RLENGTH-7);
+
+  # take apart the filename
+  split(file,X,"/");
+  if (thistarget ~ /^#/) {
+    # local name, use directory and filename
+    target = file thistarget
+  } else {
+    # different file, only use directory
+    target = X[1] "/" thistarget
+  }
+
+  # visible text
+  gsub("</a>","",line);
+  start = index(line,"\">") + 2;
+  thistext = substr(line,start);
+
+  # Assemble and store the HTML for later output.
+  entry[entries++] = "<li><a href=\"" target "\">" thistext "</a></li>"
+}
+
+# vim:sw=2

libstdc++-v3/include/bits/char_traits.h

@@ -42,17 +42,21 @@
 
 #pragma GCC system_header
 
-#include <cstring> 	// For memmove, memset, memchr
-#include <bits/fpos.h> 		// For streampos
+#include <cstring>            // For memmove, memset, memchr
+#include <bits/fpos.h>        // For streampos
 
 namespace std 
 {
-  // 21.1.2
+  // 21.1
   /**
    *  @brief  Basis for explicit traits specializations.
    *
    *  @note  For any given actual character type, this definition is
    *  probably wrong.
+   *
+   *  See http://gcc.gnu.org/onlinedocs/libstdc++/21_strings/howto.html#5
+   *  for advice on how to make use of this class for "unusual" character
+   *  types.
   */
   template<class _CharT>
     struct char_traits
@@ -108,7 +112,7 @@ namespace std
     };
 
 
-  /// 21.1.4  char_traits specializations
+  /// 21.1.3.1  char_traits specializations
   template<>
     struct char_traits<char>
     {
@@ -178,6 +182,7 @@ namespace std
 
 
 #ifdef _GLIBCPP_USE_WCHAR_T
+  /// 21.1.3.2  char_traits specializations
   template<>
     struct char_traits<wchar_t>
     {

libstdc++-v3/include/bits/stringfwd.h

@@ -60,7 +60,9 @@ namespace std
            typename _Alloc = allocator<_CharT> >
     class basic_string;
 
+  /// 99%% of %string users only ever [need to] see the typedef.
   typedef basic_string<char>    string;
+  /// 99%% of %wstring users only ever [need to] see the typedef.
   typedef basic_string<wchar_t> wstring;
 } // namespace std