[SCM] Gerris Flow Solver branch, upstream, updated. b3aa46814a06c9cb2912790b23916ffb44f1f203
Stephane Popinet
s.popinet at niwa.co.nz
Fri May 15 02:51:42 UTC 2009
The following commit has been merged in the upstream branch:
commit f490f9d85cab26482af9e6789e79d7ccf35959c7
Author: Stephane Popinet <s.popinet at niwa.co.nz>
Date: Wed Mar 16 16:22:31 2005 +1100
gfs2doc script for automatically generated example documentation
Also improved cross-links for colorised parameter files.
darcs-hash:20050316052231-fbd8f-5a0b4dd8c2c1f536ada928983bcb598269c9f8df.gz
diff --git a/configure.in b/configure.in
index e14348e..7b2b75f 100644
--- a/configure.in
+++ b/configure.in
@@ -416,4 +416,5 @@ test/tension/Makefile
doc/Makefile
doc/tutorial/Makefile
doc/examples/Makefile
+doc/examples/gfs2doc
])
diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
index ecd2aa7..66348b5 100644
--- a/doc/examples/Makefile.am
+++ b/doc/examples/Makefile.am
@@ -9,13 +9,23 @@ EXTRA_DIST = \
gfs2tex.py \
gfs2tex
+bin_SCRIPTS = \
+ gfs2doc
+
+BUILT_SOURCES= \
+ gfs2doc
+
+CLEANFILES = $(BUILT_SOURCES)
+
+dist_pkglib_DATA = gfs2tex.py
+
+gfs2doc: gfs2doc.in
+
clean-generic:
$(RM) *.dvi *.aux *.log *.toc *.out examples.tex *.pyc
-examples.tar.gz: examples.ps.gz
+examples: examples.ps.gz
latex2html -no_math -html_version 3.2,math -address "" -info "" -split +3 -show_section_numbers -toc_depth 5 -t "Gerris Examples" -local_icons -white examples.tex
- tar cf examples.tar examples
- gzip -f --best examples.tar
examples.dvi: examples.tex
latex -interaction=nonstopmode examples.tex > /dev/null 2>&1
diff --git a/doc/examples/cylinder/cylinder.gfs b/doc/examples/cylinder/cylinder.gfs
index a1f8861..0e4bce6 100644
--- a/doc/examples/cylinder/cylinder.gfs
+++ b/doc/examples/cylinder/cylinder.gfs
@@ -36,7 +36,7 @@
# Author: St\'ephane Popinet
# Command: gerris2D cylinder.gfs
# Version: 0.6.4
-# Required files: cylinder.gfs cylinder.gts
+# Required files: cylinder.gts
# Running time: 32 minutes
# Generated files: t.mpg vort.mpg t.eps vort.eps
#
diff --git a/doc/examples/cylinder/heated/heated.gfs b/doc/examples/cylinder/heated/heated.gfs
index 49e6e6a..f15a340 100644
--- a/doc/examples/cylinder/heated/heated.gfs
+++ b/doc/examples/cylinder/heated/heated.gfs
@@ -21,7 +21,7 @@
# Author: St\'ephane Popinet
# Command: gerris2D heated.gfs
# Version: 0.6.4
-# Required files: heated.gfs ../cylinder.gts
+# Required files: ../cylinder.gts
# Running time: 22 minutes
# Generated files: t.mpg t.eps
#
diff --git a/doc/examples/gfs2doc.in b/doc/examples/gfs2doc.in
new file mode 100755
index 0000000..b5b4e94
--- /dev/null
+++ b/doc/examples/gfs2doc.in
@@ -0,0 +1,73 @@
+#!/usr/bin/python
+
+import sys
+import os
+import stat
+import glob
+import tempfile
+
+sys.path.append("@prefix@/lib/gerris")
+import gfs2tex
+
+if len(sys.argv) < 2:
+ print "usage: gfs2doc DIR1 DIR2..."
+ sys.exit(1)
+
+dico = {}
+for f in glob.glob("@abs_top_srcdir@/doc/reference/*.html"):
+ gfs2tex.dictionary(dico,open(f))
+
+for d in sys.argv[1:]:
+ example = gfs2tex.Example("./" + d)
+ example.write(dico)
+ wdname = tempfile.mkdtemp()
+ tex = open(wdname + "/" + example.name + ".tex", "w")
+ tex.write(r"""
+ \documentclass[a4paper]{article}
+ \usepackage{html}
+ \usepackage{color}
+ \usepackage{graphicx}
+ \pagecolor{white}
+
+ \oddsidemargin=4mm
+ \evensidemargin=-1mm
+ \topmargin=-7mm
+ \textwidth=15.42cm
+ \textheight=23.2cm
+
+ \begin{document}
+ \section{Examples}
+ """)
+ tex.write(r"\input{" + example.name + "/" + example.name + ".tex" + "}\n")
+ tex.write("\\end{document}\n")
+ tex.close()
+ os.symlink(os.getcwd() + "/" + example.name, wdname + "/" + example.name)
+ if not os.system("rm -r -f " + example.name + ".pdf " + example.name + "_html" +\
+ "&& cd " + wdname + \
+ "&& latex -interaction=nonstopmode > /dev/null 2>&1 " + example.name + ".tex" +\
+ "&& latex -interaction=nonstopmode " + example.name + ".tex") and \
+ not os.system("cd " + wdname + \
+ "&& dvips -Ppdf -G0 " + example.name + ".dvi -o " + example.name + ".ps" +\
+ "&& ps2pdf -sPAPERSIZE=a4 -dMaxSubsetPct=100 -dCompatibilityLevel=1.2 -dSubsetFonts=true -dEmbedAllFonts=true " + example.name + ".ps " + example.name + ".pdf" +\
+ "&& mv " + example.name + ".pdf " + os.getcwd()):
+ print "\n\nSuccessfully generated file: " + example.name + ".pdf"
+ hname = wdname + "/" + example.name + "_html"
+ os.mkdir(hname)
+ os.symlink("../" + example.name, hname + "/" + example.name)
+ if not os.system("cd " + wdname + \
+ "&& latex2html -dir " + hname + " -no_math -html_version 3.2,math -address \"\" -info \"\" -split 0 -no_navigation -t \"Example " + example.name + "\" -white " + \
+ example.name + ".tex" + \
+ "&& mv " + hname + " " + os.getcwd()):
+ print "\n\nSuccessfully generated directory: " + example.name + "_html"
+ files = example.name + "/" + example.name + ".gfs"
+ for f in example.required:
+ files += " " + example.name + "/" + f
+ if not os.system("tar czf " + example.name + ".tgz " + files):
+ print "Successfully generated file: " + example.name + ".tgz"
+ else:
+ print "Errors occured while generating file: " + example.name + ".tgz"
+ else:
+ print "\n\nErrors occured while generating directory: " + example.name + "_html"
+ else:
+ print "\n\nErrors occured while generating file: " + example.name + ".pdf"
+ os.system("rm -r -f " + wdname)
diff --git a/doc/examples/gfs2tex b/doc/examples/gfs2tex
index 37a0e53..e0f4d81 100755
--- a/doc/examples/gfs2tex
+++ b/doc/examples/gfs2tex
@@ -10,8 +10,8 @@ if not os.access("examples",os.F_OK):
os.mkdir("examples")
dico = {}
-for f in glob.glob("../html/*.html"):
- gfs2tex.dictionary(dico,"file:/home/popinet/adds/src/gerris-stable/doc/html",open(f))
+for f in glob.glob("../reference/*.html"):
+ gfs2tex.dictionary(dico,open(f))
for root, dirs, files in os.walk("."):
for d in dirs:
diff --git a/doc/examples/gfs2tex.py b/doc/examples/gfs2tex.py
index 0eca9b1..fab0ada 100644
--- a/doc/examples/gfs2tex.py
+++ b/doc/examples/gfs2tex.py
@@ -11,19 +11,36 @@ def generated(lines):
return record[3:]
return []
-def dictionary(d,path,file):
+def dictionary(d,file):
+ p = re.compile(r">\w*_class</A\n")
instruct = 0
for line in file:
record = line.split()
- if len(record) == 2 and record[0] == "struct" and record[1] == "<A":
+ if re.match(p,line) != None:
+ klass = ""
+ cap = 1
+ for c in line[1:-9]:
+ if c == "_":
+ cap = 1
+ elif cap:
+ klass += c.capitalize()
+ cap = 0
+ else:
+ klass += c
+ if klass == "GfsOutputPpm":
+ klass = "GfsOutputPPM"
+ d[klass] = href
+ elif len(record) == 2 and record[0] == "struct" and record[1] == "<A":
instruct = 1
elif len(record) == 1 and record[0] == ">;":
instruct = 0
elif instruct:
if line[0:5] == "HREF=":
- val = path + "/" + line[6:-2]
+ val = line[6:-2]
elif line[0] == ">" and line[-4:] == "</A\n":
d[line[1:-4]] = val
+ elif line[0:5] == "HREF=":
+ href = line[6:line.find("#")]
class Example:
def __init__(self,path):
@@ -92,14 +109,12 @@ class Example:
file.write("\\item[Author]" + self.author + "\n")
file.write("\\item[Command]" + "{\\tt " + self.command + "}\n")
file.write("\\item[Version]" + self.version + "\n")
- required = ""
+ f = self.name + ".gfs"
+ required = " " + f + \
+ " \\htmladdnormallinkfoot{(view)}{" + self.path + "/" + f + ".html}" +\
+ " \\htmladdnormallinkfoot{(download)}{" + self.path + "/" + f + "}\\\\"
for f in self.required:
- if f[-4:] == ".gfs":
- required += " " + f + \
- " \\htmladdnormallinkfoot{(view)}{" + self.path + "/" + f + ".html}" +\
- " \\htmladdnormallinkfoot{(download)}{" + self.path + "/" + f + "}\\\\"
- else:
- required += " \\htmladdnormallinkfoot{" + f + "}{" + self.path + "/" + f + "}"
+ required += " \\htmladdnormallinkfoot{" + f + "}{" + self.path + "/" + f + "}"
file.write("\\item[Required files]" + required + "\n")
file.write("\\item[Running time]" + self.time + "\n")
file.write("\\end{description}\n")
@@ -109,7 +124,9 @@ class Example:
def colorize(self,dico):
file = open(self.path + "/" + self.name + ".gfs")
out = open(self.path + "/" + self.name + ".gfs.html", 'w')
- out.write("<html>\n<body>\n")
+ path = "../" * (self.path.count("/") + 2) + "reference/"
+ out.write("<html><head><title>\n" + self.name + ".gfs")
+ out.write("</title></head><body><tt>\n")
infile = insthg = 0
for line in file:
l = ""
@@ -152,8 +169,8 @@ class Example:
elif dico.has_key("Gfs" + r):
key = "Gfs" + r
if key != None:
- out.write("<a href=\"" + dico[key] + "\">" + r + "</a> ")
+ out.write("<a href=\"" + path + dico[key] + "\">" + r + "</a> ")
else:
out.write(r + " ")
out.write("<br>\n")
- out.write("</body>\n</html>\n")
+ out.write("</tt></body>\n</html>\n")
diff --git a/doc/examples/template.tex b/doc/examples/template.tex
index 78cd05d..44e9d0a 100644
--- a/doc/examples/template.tex
+++ b/doc/examples/template.tex
@@ -17,15 +17,25 @@
{\huge Gerris examples}\\
{\large Version 0.6.4}\\
\vspace{5mm}
-{\large St\'ephane Popinet\\
-{\tt s.popinet at niwa.cri.nz}\\
+{\large St\'ephane Popinet
\vspace{5mm}
\today}
\vspace{1cm}
\end{center}
\tableofcontents
-\newpage
+
+\section{Introduction}
+
+This document is a collection of examples contributed by Gerris users and intended to illustrate the range of applications where Gerris is applicable. It should also serve as a useful starting point for customised applications.
+
+The sections in this document are a rough classification of the various applications. In particular, an example appearing in a subsection usually indicates that this example is a relatively small incremental change over the parent example appearing in the section above it.
+
+Gerris parameter files are commented and cross-linked with the \htmladdnormallinkfoot{Gerris Reference Manual}{http://gfs.sf.net/reference/book1.html}. As a rule, the first examples in the document contain comments for most of the instructions in the parameter file. Latter examples only contain comments for the relevant new instructions or for more complex usage of already introduced instructions.
+
+The indicative running times given are representative of the running time on an Intel 2.4 GHz processor.
+
+The usefulness and quality of this document very much depend on the contributions of users. If you think you have used Gerris in an interesting way which is not already covered by the existing examples, you are very welcome to contribute. Have a look at section \ref{howto} for instructions on how to do that.
\section{2D}
@@ -33,5 +43,38 @@
\input{cylinder/heated/heated.tex}
\section{How to write examples}
+\label{howto}
+
+This document is generated automatically using self-documenting Gerris parameter files. If you look at \htmladdnormallinkfoot{any}{cylinder/cylinder.gfs} of the {\tt .gfs} files in this document you will see that apart from comments on specific instructions, the top of the file contains fields which describe the simulation. They are:
+\begin{description}
+\item[Title:] the title of the simulation.
+\item[Description:] a Latex block of text describing the simulation. It can contain figures, tables, equations etc\dots
+\item[Author:] you.
+\item[Command:] the exact command needed to run the example.
+\item[Version:] the version of Gerris you used (output of {\tt gerris2D -V}).
+\item[Required files:] any file (e.g. GTS files etc\dots) other than the Gerris simulation file required to run the simulation. Try to keep the total size of these files reasonable.
+\item[Running time:] the approximate total running time of the simulation. This is of course machine-dependent but must be appropriately scaled to be representative of the running time on an Intel 2.4 GHz processor.
+\item[Generated files:] any file (movies, images, curves etc\dots) generated by the simulation.
+\end{description}
+Apart from the ``Description:'' field all the fields must fit on a single line just after the field name.
+
+Any extra data you need for the description (e.g. figures as EPS files) must be generated by the simulation. Have a look at other examples to see how this can be done.
+
+Once you have an initial draft for your documented parameter file, you need to package it like this:
+\begin{enumerate}
+\item Choose a short name for your example. This short name should not already be used by any of the examples in this document. Let's say {\tt myexample}.
+\item Create a directory {\tt myexample}.
+\item Copy your parameter file in {\tt myexample/myexample.gfs}. You must use the same name for the directory and the parameter file.
+\item Copy any other file you need (as listed in the ``Required files:'' field) in {\tt myexample}.
+\item Cd to {\tt myexample} and re-run the simulation (using the command listed in the ``Command:'' field) or alternatively copy the previously generated files listed in the ``Generated files:'' field into {\tt myexample}.
+\item Cd to {\tt myexample/..}
+\item\label{gendoc} Generate the HTML and PDF documentation for your example using:
+\begin{verbatim}
+% gfs2doc myexample
+\end{verbatim}
+Note that this script requires Latex and latex2html.
+\item Check that the {\tt myexample\_html/index.html} and {\tt myexample.pdf} files are to your liking. If they are not, edit your parameter file and return to \ref{gendoc}.
+\item Send me ({\tt s.popinet at niwa.cri.nz}) your example ({\tt myexample.tgz} as an attachment). Tell me which section, subsection you think it would most naturally fit in (or request a new section). I will then review it and integrate it in this document.
+\end{enumerate}
\end{document}
--
Gerris Flow Solver
More information about the debian-science-commits
mailing list