From: wolf Date: Thu, 16 Mar 2006 02:37:58 +0000 (+0000) Subject: Generate some sort of doxygen output. Not finished yet, though. X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4822bb2e31afad7e74d4cf7c85e05b257ca15671;p=dealii-svn.git Generate some sort of doxygen output. Not finished yet, though. git-svn-id: https://svn.dealii.org/trunk@12609 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/Makefile b/deal.II/doc/tutorial/chapter-2.step-by-step/Makefile index fc9901635b..e6a3808ea9 100644 --- a/deal.II/doc/tutorial/chapter-2.step-by-step/Makefile +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/Makefile @@ -14,25 +14,34 @@ gen-example-names = $(addprefix generated/, $(example-names)) # names of commented program files, plain files, and tocs for the commented # and commented and plain versions of the program as well as a combined one -example-progs = $(addsuffix _prog.html,$(gen-example-names)) +example-prog = $(addsuffix _prog.html,$(gen-example-names)) example-plain = $(addsuffix _plain.html,$(gen-example-names)) example-toc-prog = $(addsuffix _toc.prog,$(gen-example-names)) example-toc-plain = $(addsuffix _toc.plain,$(gen-example-names)) example-toc = $(addsuffix _toc.combined,$(gen-example-names)) +# same for intermediate files for doxygen output +example-dox-prog = $(addsuffix _prog.dox,$(gen-example-names)) +example-dox-plain = $(addsuffix _plain.dox,$(gen-example-names)) + + # finally a target for combined HTML files example-htmls = $(addsuffix .html,$(example-names)) +example-doxygen = $(addprefix doxygen/,$(addsuffix .h,$(example-names))) + + + # a makefile command that extracts the base name of a program -get_basename = $(shell echo $(1) | $(PERL) -pi -e 's/generated.//g; s/\..*//g; s/_(prog|plain|toc.*)//g;') +get_basename = $(shell echo $(1) | $(PERL) -pi -e 's/(generated|doxygen).//g; s/\..*//g; s/_(prog|plain|toc.*)//g;') -all: $(example-htmls) +all: $(example-htmls) $(example-doxygen) -$(example-progs): +$(example-prog): @echo ================== Making $@ @cat $D/examples/$(call get_basename, $@)/*.cc \ | $(PERL) program2html \ @@ -84,7 +93,7 @@ $(example-toc): $(example-htmls): @echo ================== Assembling $@ @cat head.html > $@ - @echo "

Overview of $(call get_basename,$@)

" >> $@ + @echo "

Overview of $(call get_basename,$@)

" >> $@ @cat generated/$(call get_basename, $@)_toc.combined \ $(call get_basename, $@).data/intro.html \ generated/$(call get_basename, $@)_prog.html \ @@ -94,6 +103,39 @@ $(example-htmls): +$(example-dox-prog): + @echo ================== Making $@ + @cat $D/examples/$(call get_basename, $@)/*.cc \ + | $(PERL) program2doxygen \ + > $@ + + +$(example-dox-plain): + @echo ================== Making $@ + @echo " * " > $@ + @echo " *

The plain program

" >> $@ + @echo " * " >> $@ + @echo " * (If you are looking at a locally installed deal.II version, then the" >> $@ + @echo " * program can be found at " >> $@ + @echo " * " $D/examples/$(call get_basename,$@)/*.cc | $(PERL) -pi -e 's!/! /!g;' >> $@ + @echo " * . Otherwise, this is only" >> $@ + @echo " * the path on some remote server.)" >> $@ + @echo " * @code" >> $@ + @cat $D/examples/$(call get_basename, $@)/*.cc | $(PERL) program2doxyplain >> $@ + @echo " * @endcode" >> $@ + + +$(example-doxygen): + @echo ================== Assembling $@ + @echo "/**" > $@ + @echo " * @page $(shell echo $(call get_basename,$@) | $(PERL) -pi -e 's/-/_/g;') \ + $(call get_basename,$@)" >> $@ + @echo " *

Overview of $(call get_basename,$@)

" >> $@ + @cat generated/$(call get_basename, $@)_prog.dox \ + generated/$(call get_basename, $@)_plain.dox \ + >> $@ + @echo " */" >> $@ + validate-xrefs: @$(PERL) $D/common/scripts/validate-xrefs.pl \ @@ -103,8 +145,9 @@ validate-xrefs: clean: -rm -f $(example-htmls) - -rm -f $(example-progs) $(example-plain) $(example-toc) \ - $(example-toc-prog) $(example-toc-plain) + -rm -f $(example-prog) $(example-plain) $(example-toc) \ + $(example-toc-prog) $(example-toc-plain) \ + $(example-dox-prog) $(example-dox-plain) $(example-doxygen) .PHONY: validate-xrefs clean @@ -114,7 +157,8 @@ Makefile.dep: $(shell echo $D/examples/*/*.cc) Makefile @echo ================== Generating $@ @for i in $(example-names) ; do \ echo generated/$${i}_prog.html generated/$${i}_plain.html \ - generated/$${i}_toc.prog : \ + generated/$${i}_toc.prog \ + generated/$${i}_prog.dox generated/$${i}_plain.dox : \ `echo $D/examples/*/$${i}.cc` ; \ echo generated/$${i}_toc.plain : generated/$${i}_toc.prog ; \ echo generated/$${i}_toc.combined : \ @@ -122,6 +166,9 @@ Makefile.dep: $(shell echo $D/examples/*/*.cc) Makefile echo $$i.html : generated/$${i}_prog.html generated/$${i}_plain.html \ generated/$${i}_toc.combined \ $$i.data/intro.html $$i.data/results.html ; \ + echo doxygen/$$i.h : generated/$${i}_prog.dox generated/$${i}_plain.dox \ + generated/$${i}_toc.combined \ + $$i.data/intro.html $$i.data/results.html ; \ done \ > $@ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxygen b/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxygen new file mode 100644 index 0000000000..4b7c6b1197 --- /dev/null +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxygen @@ -0,0 +1,77 @@ +# Copyright (C) 1999, 2000, 2001, 2002, 2005, 2006 by Wolfgang Bangerth, University of Heidelberg + +print " *

The commented program

\n"; + +# ignore comments at the start of the program. this includes CVS +# tags and copyright notices. +$_ = <>; +while ( m!^/[/\*]! || m!\s*\*! || m/^$/ ) { + $_ = <>; +} + +# have two states, in which the program can be: +# comment-mode and program-mode +$comment_mode = 0; +$program_mode = 1; +$state = $comment_mode; + +print " * \n"; + +do { + # substitute special characters + s/\t/ /g; + + if (($state == $program_mode) && m!^\s*//!) + { + $state = $comment_mode; + print " * \@endcode\n"; + print " * \n"; + } + # if in comment mode and no comment line: toggle state. + # don't do so, if only a blank line + elsif (($state == $comment_mode) && !m!^\s*//! && !m!^\s*$!) + { + $state = $program_mode; + print " * \n"; + print " * \@code\n"; + } + + if ($state == $comment_mode) + { + # in comment mode: first skip leading whitespace and + # comment // signs + s!\s*//\s*(.*)\n!$1!; + + # make sure template arguments are printed correctly + s!!\@>!g; + + # second, replace section headers, and generate addressable + # anchor + if ( /\@sect/ ) { + s!\@sect(\d)\{(.*)\}\s*$!$2!g; + $sect_name = $2; + $sect_name =~ s/\s/_/g; + $sect_name =~ s/[\'\`]/_/g; + $_ = "\n * \n * $_"; + } + + # then replace references to other example programs automatically: + s!step-(\d+)!\@ref step_\1 \"step-\1\"!g; + + # finally print this line + print " * $_\n"; + + # if empty line, introduce paragraph break + print " * \n" if $_ =~ m!^\s*$!; + } + else + { + print " * $_"; + } +} while (<>); + +if ($state == $program_mode) { + print " * \@endcode\n"; +} + diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxygen~ b/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxygen~ new file mode 100644 index 0000000000..de8178f2cf --- /dev/null +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxygen~ @@ -0,0 +1,77 @@ +# Copyright (C) 1999, 2000, 2001, 2002, 2005, 2006 by Wolfgang Bangerth, University of Heidelberg + +print " *

The commented program

\n"; + +# ignore comments at the start of the program. this includes CVS +# tags and copyright notices. +$_ = <>; +while ( m!^/[/\*]! || m!\s*\*! || m/^$/ ) { + $_ = <>; +} + +# have two states, in which the program can be: +# comment-mode and program-mode +$comment_mode = 0; +$program_mode = 1; +$state = $comment_mode; + +print " * \n"; + +do { + # substitute special characters + s/\t/ /g; + + if (($state == $program_mode) && m!^\s*//!) + { + $state = $comment_mode; + print " * \@endcode\n"; + print " * \n"; + } + # if in comment mode and no comment line: toggle state. + # don't do so, if only a blank line + elsif (($state == $comment_mode) && !m!^\s*//! && !m!^\s*$!) + { + $state = $program_mode; + print " * \n"; + print " * \@code\n"; + } + + if ($state == $comment_mode) + { + # in comment mode: first skip leading whitespace and + # comment // signs + s!\s*//\s*(.*)\n!$1!; + + # make sure template arguments are printed correctly + s!!\@>!g; + + # second, replace section headers, and generate addressable + # anchor + if ( /\@sect/ ) { + s!\@sect(\d)\{(.*)\}\s*$!$2!g; + $sect_name = $2; + $sect_name =~ s/\s/_/g; + $sect_name =~ s/[\'\`]/_/g; + $_ = "\n * \@anchor $sect_name \n * $_"; + } + + # then replace references to other example programs automatically: + s!step-(\d+)!\@ref step_\1 \"step-\1\"!g; + + # finally print this line + print " * $_\n"; + + # if empty line, introduce paragraph break + print " * \n" if $_ =~ m!^\s*$!; + } + else + { + print " * $_"; + } +} while (<>); + +if ($state == $program_mode) { + print " * \@endcode\n"; +} + diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxyplain b/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxyplain new file mode 100644 index 0000000000..d738e68c3a --- /dev/null +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxyplain @@ -0,0 +1,28 @@ +# Copyright (C) 2006 by Wolfgang Bangerth, Texas A&M University + +print "\n"; + + +while (<>) { + # simply print non-comment lines and let doxygen do all the work + if ( ! m!^\s*//! ) { + print " * $_"; + } else { + # for comments, all we do is replace section headers, and + # generate addressable anchors + if ( /\@sect/ ) { + # replace quotation marks by the appropriate HTML quotation marks + s!``!“!g; + s!''!”!g; + + # replace double dashes in comments by — + s!--!—!g; + + m!\@sect(\d)\{(.*)\}\s*$!; + $sect_name = $2; + $sect_name =~ s/\s/_/g; + $_ = " * \n"; + print; + } + } +} diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxyplain~ b/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxyplain~ new file mode 100644 index 0000000000..380da8b56c --- /dev/null +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/program2doxyplain~ @@ -0,0 +1,37 @@ +# Copyright (C) 1999, 2000, 2001, 2002, 2006 by Wolfgang Bangerth, University of Heidelberg + +print "

\n"; +print "

\n";
+
+
+while (<>) {
+    # ignore comment lines
+    if ( ! m!^\s*//! ) {
+	# substitute special characters
+	s/&/&/g; 
+	s//>/g;
+	s/\t/        /g;
+
+	print "  $_";
+    } else {
+	# second, replace section headers, and generate addressable
+	# anchor
+	if ( /\@sect/ ) {
+	   # replace quotation marks by the appropriate HTML quotation marks
+	   s!``!“!g;
+	   s!''!”!g;
+
+           # replace double dashes in comments by —
+	   s!--!—!g;
+
+	   m!\@sect(\d)\{(.*)\}\s*$!;
+	   $sect_name = $2;
+	   $sect_name =~ s/\s/_/g;
+	   $_ = "\n";
+	   print;
+	}
+    }	
+}
+
+print "
\n

\n\n";