# 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 \
$(example-htmls):
@echo ================== Assembling $@
@cat head.html > $@
- @echo "<h2>Overview of $(call get_basename,$@)</h2>" >> $@
+ @echo "<h1>Overview of $(call get_basename,$@)</h1>" >> $@
@cat generated/$(call get_basename, $@)_toc.combined \
$(call get_basename, $@).data/intro.html \
generated/$(call get_basename, $@)_prog.html \
+$(example-dox-prog):
+ @echo ================== Making $@
+ @cat $D/examples/$(call get_basename, $@)/*.cc \
+ | $(PERL) program2doxygen \
+ > $@
+
+
+$(example-dox-plain):
+ @echo ================== Making $@
+ @echo " * <a name=\"PlainProg\"></a>" > $@
+ @echo " * <h1> The plain program</h1>" >> $@
+ @echo " * " >> $@
+ @echo " * (If you are looking at a locally installed deal.II version, then the" >> $@
+ @echo " * program can be found at <i>" >> $@
+ @echo " * " $D/examples/$(call get_basename,$@)/*.cc | $(PERL) -pi -e 's!/! /!g;' >> $@
+ @echo " * </i>. 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 " * <h1>Overview of $(call get_basename,$@)</h1>" >> $@
+ @cat generated/$(call get_basename, $@)_prog.dox \
+ generated/$(call get_basename, $@)_plain.dox \
+ >> $@
+ @echo " */" >> $@
+
validate-xrefs:
@$(PERL) $D/common/scripts/validate-xrefs.pl \
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
@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 : \
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 \
> $@
--- /dev/null
+# Copyright (C) 1999, 2000, 2001, 2002, 2005, 2006 by Wolfgang Bangerth, University of Heidelberg
+
+print " * <h1> The commented program</h1>\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;
+ s!>!\@>!g;
+
+ # second, replace section headers, and generate addressable
+ # anchor
+ if ( /\@sect/ ) {
+ s!\@sect(\d)\{(.*)\}\s*$!<h$1>$2</h$1>!g;
+ $sect_name = $2;
+ $sect_name =~ s/\s/_/g;
+ $sect_name =~ s/[\'\`]/_/g;
+ $_ = "\n * <a name=\"$sect_name\"></a> \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";
+}
+
--- /dev/null
+# Copyright (C) 1999, 2000, 2001, 2002, 2005, 2006 by Wolfgang Bangerth, University of Heidelberg
+
+print " * <h1> The commented program</h1>\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;
+ s!>!\@>!g;
+
+ # second, replace section headers, and generate addressable
+ # anchor
+ if ( /\@sect/ ) {
+ s!\@sect(\d)\{(.*)\}\s*$!<h$1>$2</h$1>!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";
+}
+
--- /dev/null
+# 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;
+ $_ = " * <a name=\"plain-$sect_name\"></a>\n";
+ print;
+ }
+ }
+}
--- /dev/null
+# Copyright (C) 1999, 2000, 2001, 2002, 2006 by Wolfgang Bangerth, University of Heidelberg
+
+print "<p>\n";
+print "<pre><code>\n";
+
+
+while (<>) {
+ # ignore comment lines
+ if ( ! m!^\s*//! ) {
+ # substitute special characters
+ s/&/&/g;
+ 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<a name=\"plain-$sect_name\"></a>";
+ print;
+ }
+ }
+}
+
+print "</code></pre>\n</p>\n\n";