]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Generate some sort of doxygen output. Not finished yet, though.
authorwolf <wolf@0785d39b-7218-0410-832d-ea1e28bc413d>
Thu, 16 Mar 2006 02:37:58 +0000 (02:37 +0000)
committerwolf <wolf@0785d39b-7218-0410-832d-ea1e28bc413d>
Thu, 16 Mar 2006 02:37:58 +0000 (02:37 +0000)
git-svn-id: https://svn.dealii.org/trunk@12609 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/doc/tutorial/chapter-2.step-by-step/Makefile
deal.II/doc/tutorial/chapter-2.step-by-step/program2doxygen [new file with mode: 0644]
deal.II/doc/tutorial/chapter-2.step-by-step/program2doxygen~ [new file with mode: 0644]
deal.II/doc/tutorial/chapter-2.step-by-step/program2doxyplain [new file with mode: 0644]
deal.II/doc/tutorial/chapter-2.step-by-step/program2doxyplain~ [new file with mode: 0644]

index fc9901635ba7506d521d8a28763c9cb1c2b1b90c..e6a3808ea950b8f599475d9ef6d1d3c861e5f20e 100644 (file)
@@ -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 "<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   \
@@ -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 " * <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 \
@@ -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 (file)
index 0000000..4b7c6b1
--- /dev/null
@@ -0,0 +1,77 @@
+# 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";
+}
+
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 (file)
index 0000000..de8178f
--- /dev/null
@@ -0,0 +1,77 @@
+# 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";
+}
+
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 (file)
index 0000000..d738e68
--- /dev/null
@@ -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!``!&#8220;!g;
+          s!''!&#8221;!g;
+
+           # replace double dashes in comments by &mdash;
+          s!--!&mdash;!g;
+
+          m!\@sect(\d)\{(.*)\}\s*$!;
+          $sect_name = $2;
+          $sect_name =~ s/\s/_/g;
+          $_ = " * <a name=\"plain-$sect_name\"></a>\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 (file)
index 0000000..380da8b
--- /dev/null
@@ -0,0 +1,37 @@
+# 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/&/&amp;/g; 
+       s/</&lt;/g;      
+       s/>/&gt;/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!``!&#8220;!g;
+          s!''!&#8221;!g;
+
+           # replace double dashes in comments by &mdash;
+          s!--!&mdash;!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";

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.