[libstdc++] automate documentation.html changes, basic_string doxygen hooks

[Jonathan Wakely]

On Sat, Aug 31, 2002 at 08:33:28PM -0400, Phil Edwards wrote:

> string, wstring, and basic_string hav never been doxygenated.  This adds
> the initial hooks to make them at least show up the output.

Am I right in thinking the algorithm Doxygen comments don't come out in
the manpage versions yet?

Once I've got the wwwdocs as XHTML I'll be glad to continue adding Doxygen
comments to the sources, starting with basic_string if you like.

> Benjmain recently copied out all of the "Contents" blocks from our
> various HOWTOs into an expanded form in the parent documentation.html.
> To avoid repetitious editing, this makes documentation.html a target in
> docs/html/Makefile.  So, for example, after editing 21_strings/howto.html
> to add a new entry, it automatically showed up in the expanded list.
> (The initial regen changed indentation on all those lines, and added </li>
> also, so the diff is large.)

I've merged this with my XHTML changes (adding </li> was required there
anyway :-) and found a couple of problems:

[[:digit:]] as a shell wildcard is a Bash-ism (well, POSIXsim, whatever),
which chokes /bin/sh on BSD.
I don't know if [0-9] is totally portable either, but it WorksForMe.

$(wildcard ...) is a GNU make feature, not supported on BSD make, so you
can't regenerate documentation.html without either marking that target
as .PHONY or using gmake (or so my 10 minutes testing indicated.)

I propose the following patch for the shell wildcard:

2002-09-02  Jonathan Wakely <jw@kayari.org>

	* docs/html/Makefile: Use more portable shell wildcard.



Index: Makefile
===================================================================
RCS file: /cvsroot/gcc/gcc/libstdc++-v3/docs/html/Makefile,v
retrieving revision 1.5
diff -c -5 -r1.5 Makefile
*** Makefile    1 Sep 2002 00:33:51 -0000       1.5
--- Makefile    2 Sep 2002 12:30:53 -0000
***************
*** 11,21 ****
  # 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"\
--- 11,21 ----
  # 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 [0-9]*/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"\


As for the $(wildcard ...) problem I'll use GNU for now.

I think I need to (slightly) change makedoc.awk to convert the docs to XHTML,
but I'll check that against a clean tree and submit it with the XHTML
patch.


jon


-- 
I listen a lot and talk less. You can't learn anything when you're talking.
	- Bing Crosby