[doconce] push by h...@simula.no - Recompiled manuals. Moved _abort() function to common and it is now us... on 2013-06-28 16:22 GMT
9 views
Skip to first unread message
doc...@googlecode.com
Jun 28, 2013, 12:22:57 PM6/28/13
to docon...@googlegroups.com
Revision: 17915e1da38e
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Fri Jun 28 09:22:02 2013
Log: Recompiled manuals. Moved _abort() function to common and it is
now used by all modules.
http://code.google.com/p/doconce/source/detail?r=17915e1da38e
Modified:
/doc/demos/manual/html/.buildinfo
/doc/demos/manual/html/_sources/manual.txt
/doc/demos/manual/html/_static/pygments.css
/doc/demos/manual/html/_static/searchtools.js
/doc/demos/manual/html/genindex.html
/doc/demos/manual/html/index.html
/doc/demos/manual/html/manual.html
/doc/demos/manual/html/search.html
/doc/demos/manual/html/searchindex.js
/doc/demos/manual/index.html
/doc/demos/manual/manual.cwiki
/doc/demos/manual/manual.do.txt
/doc/demos/manual/manual.epytext
/doc/demos/manual/manual.gwiki
/doc/demos/manual/manual.html
/doc/demos/manual/manual.md
/doc/demos/manual/manual.mwiki
/doc/demos/manual/manual.p.tex
/doc/demos/manual/manual.pdf
/doc/demos/manual/manual.rst
/doc/demos/manual/manual.rst.html
/doc/demos/manual/manual.rst.pdf
/doc/demos/manual/manual.rst.tex
/doc/demos/manual/manual.sphinx.rst
/doc/demos/manual/manual.tex
/doc/demos/manual/manual.txt
/doc/demos/manual/manual.xml
/doc/demos/manual/manual_pdflatex.pdf
/doc/manual/make.sh
/doc/manual/manual.do.txt
/lib/doconce/common.py
/lib/doconce/cwiki.py
/lib/doconce/doconce.py
/lib/doconce/gwiki.py
/lib/doconce/html.py
/lib/doconce/latex.py
/lib/doconce/misc.py
/lib/doconce/mwiki.py
/lib/doconce/plaintext.py
/lib/doconce/rst.py
=======================================
--- /doc/demos/manual/html/.buildinfo Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/.buildinfo Fri Jun 28 09:22:02 2013
@@ -1,4 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When
it is not found, a full rebuild will be done.
-config: b4c482109670ab5e81b9e005a0c806c3
+config: 3ea5c65044e09da28c0daa377b080bb4
tags: fbb0d17656682115ca4d033fb2f83ba1
=======================================
--- /doc/demos/manual/html/_sources/manual.txt Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/_sources/manual.txt Fri Jun 28 09:22:02 2013
@@ -5,7 +5,7 @@
===================
:Author: Hans Petter Langtangen
-:Date: May 29, 2013
+:Date: Jun 28, 2013
.. lines beginning with # are doconce comment lines
@@ -658,7 +658,7 @@
=============================
Transformation of a Doconce document ``mydoc.do.txt`` to various other
-formats applies the script ``doconce format``:
+formats apply the script ``doconce format``:
.. code-block:: console
@@ -2348,7 +2348,7 @@
(the label appears in the figure caption in the source code of this
document).
Additional references to the sections :ref:`mathtext`
and :ref:`newcommands` are
nice to demonstrate, as well as a reference to equations,
-say :eq:`myeq1`-:eq:`myeq2`. A comparison of the output and
+say (:ref:`myeq1`)-(:ref:`myeq2`). A comparison of the output and
the source of this document illustrates how labels and references
are handled by the format in question.
@@ -2500,7 +2500,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with ``===`` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in ``html`` output such that search engines can make use of the them.
Bibliography (2)
-----------------
@@ -2696,6 +2700,22 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes ``|`` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+
+.. code-block:: text
+
+
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+
+
Note that not all formats offer alignment of heading or entries
in tables (``rst`` and ``sphinx`` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2708,6 +2728,40 @@
where ``X`` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the ``doconce csv2table`` utility:
+
+
+.. code-block:: console
+
+ Terminal> doconce csv2table somefile.csv > table.do.txt
+
+This is a quick way of writing tables. For example, we can
+write a text file ``tmp.csv`` with
+
+
+.. code-block:: python
+
+ time, velocity, acceleration
+ 0.0, 1.4186, -5.01
+ 2.0, 1.376512, 11.919
+ 4.0, 1.1E+1, 14.717624
+
+Running ``doconce csv2table tmp.csv`` creates the table
+
+
+.. code-block:: text
+
+
+ |------c--------------c--------------c-------|
+ | time | velocity | acceleration |
+ |------c--------------c--------------c-------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------------------|
+
+
Exercises, Problems, Projects, and Examples
-------------------------------------------
@@ -3160,23 +3214,6 @@
\end{align}
!et
-Here is the result:
-
-
-.. math::
- :label: myeq1
-
- {\partial u\over\partial t} = \nabla^2 u + f,
-
-
-
-
-.. math::
- :label: myeq2
-
- {\partial v\over\partial t} = \nabla\cdot(q(u)\nabla v) + g.
-
-
The support of LaTeX mathematics varies among the formats:
@@ -3281,70 +3318,21 @@
newcommands in the ``newcommands*.tex`` files *must* appear on a single
line (multi-line newcommands are too hard to parse with regular
expressions).
-
-*Example.* Suppose we have the following commands in
-``newcommand_replace.tex``:
-
-
-.. code-block:: text
-
-
- \newcommand{\beqa}{\begin{eqnarray}}
- \newcommand{\eeqa}{\end{eqnarray}}
- \newcommand{\ep}{\thinspace . }
- \newcommand{\uvec}{\vec u}
- \newcommand{\Q}{\pmb{Q}}
-
-
-and these in ``newcommands_keep.tex``:
-
-
-.. code-block:: text
-
-
- \newcommand{\x}{\pmb{x}}
- \newcommand{\normalvec}{\pmb{n}}
- \newcommand{\Ddt}[1]{\frac{D#1}{dt}}
- \newcommand{\half}{\frac{1}{2}}
-The LaTeX block
-
-.. code-block:: text
-
-
- \beqa
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{\uvec} &=& \Q \ep label{my:eq2}
- \eeqa
-
-will then be rendered to
-
-.. math::
-
- \pmb{x}\cdot\pmb{n} &= 0, \\
- \frac{D{\vec u}{dt}} &= \pmb{Q} {\thinspace . }
-
-
-in the current format.
-
Admonitions
-----------
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-``block``, ``warning``, ``notice``, ``hint``, ``question``, and
``summary``.
-The box is defined by begin and end tags such as ``!bhint`` and ``!ehint``.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the ``hint`` environment gives a
-box with some admonition icon, text and/or colored background.)
+``block``, ``warning``, ``notice``, ``question``, and ``summary``.
+The box is defined by begin and end tags such as ``!bnotice`` and
``!enotice``.
The title of the box is fully customizable.
Here are a few examples:
@@ -3357,9 +3345,9 @@
Here is a warning!
!ewarning
- !bhint
+ !bnotice Hint
This is a hint.
- !ehint
+ !enotice
!bblock This is a block.
A block has never any icon.
@@ -3383,8 +3371,9 @@
.. warning::
Here is a warning!
+
+.. admonition:: Hint
-.. hint::
This is a hint.
@@ -3686,6 +3675,7 @@
Emacs Doconce Formatter
-----------------------
+
The file `.doconce-mode.el
<https://doconce.googlecode.com/hg/misc/.doconce-mode.el>`_ in the Doconce
source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3787,8 +3777,10 @@
.. font sizes are compatible
+
+Not yet written...
-Text is missing... Just a very preliminary sketch of commands:
+Just a very preliminary sketch of commands:
.. code-block:: console
@@ -3810,6 +3802,17 @@
LaTeX Beamer Slides
-------------------
+Not yet written...
+
+Themes
+~~~~~~
+
+Four themes come with Doconce: ``X_Y``, where ``X`` is ``blue`` or ``red``
+(the main color of the slides) and ``Y`` is `plain
<http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf>`_
+for simple layout and
+`shadow
<http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf>`_
+for shadowed boxes and more visual structure in the slides.
+
Mako Programming
================
@@ -3820,6 +3823,16 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+.. warning::
+ Unfortunately, the combination of Mako and LaTeX mathematics may
+ lead to problems because Mako applies syntax like ``${var}`` to extract
+ variables or call functions, while LaTeX mathematics sometimes applies
+ the same syntax, e.g., ``${\cal O}(\Delta x^2)$`` which looks like a
+ Mako function call. This problem can give rise to strange error
+ messages from Mako, usually that a variable is not defined.
+
+
The Basics of Mako
------------------
@@ -4015,6 +4028,16 @@
General Problems
----------------
+Spellcheck reports a lot of mistakes related LaTeX math
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``doconce spellcheck`` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant ``tmp_missing_*`` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
Doconce aborts because of a syntax error that is not an error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4042,6 +4065,27 @@
* Strings with ``'T<%.1f'`` look as openings of Mako blocks (``<%``);
change
to ``'T < %.1f'`` to avoid this confusion.
+The Mako preprocessor claims a variable is undefined
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, :math:`{\cal O}(\Delta x^2)` is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use ``${`` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is ``${}^+$`` type of indication of superscripts.
+A suggested rewrite is ``$\,{}^+$``.
+
+The error message will ask you to rerun ``doconce`` with
+``--mako_strict_undefined``, which will display the variable that
+is confusing Mako. However, do not continue to use
+``--mako_strict_undefined`` while you are debugging because this
+variable will then always be undefined in that mode.
+Use ``# #ifdef`` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without ``--mako_strict_undefined``).
+
Something goes wrong in the preprocessing step
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4512,6 +4556,16 @@
Problems with HTML Output
-------------------------
+MathJax formulas are not properly rendered
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ * ``[`` and ``]`` brackets must sometimes be replaced by ``\lbrack`` and
``\rbrack``
+
How can I change the layout of the HTML page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================
--- /doc/demos/manual/html/_static/pygments.css Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/_static/pygments.css Fri Jun 28 09:22:02 2013
@@ -13,11 +13,11 @@
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
-.highlight .go { color: #303030 } /* Generic.Output */
+.highlight .go { color: #333333 } /* Generic.Output */
.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading
*/
-.highlight .gt { color: #0040D0 } /* Generic.Traceback */
+.highlight .gt { color: #0044DD } /* Generic.Traceback */
.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #007020; font-weight: bold } /*
Keyword.Declaration */
.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace
*/
=======================================
--- /doc/demos/manual/html/_static/searchtools.js Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/_static/searchtools.js Fri Jun 28 09:22:02 2013
@@ -301,7 +301,7 @@
},
query : function(query) {
- var stopwords =
["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"];
+ var stopwords =
["and","then","into","it","as","are","in","if","for","no","there","their","was","is","be","to","that","but","they","not","such","with","by","a","on","these","of","will","this","near","the","or","at"];
// Stem the searchterms and add them to the correct list
var stemmer = new Stemmer();
=======================================
--- /doc/demos/manual/html/genindex.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/genindex.html Fri Jun 28 09:22:02 2013
@@ -17,7 +17,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
- URL_ROOT: './',
+ URL_ROOT: '',
VERSION: '0.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
@@ -267,7 +267,7 @@
</div>
<div class="footer">
© Copyright 2013, HPL.
- Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2pre.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
=======================================
--- /doc/demos/manual/html/index.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/index.html Fri Jun 28 09:22:02 2013
@@ -15,7 +15,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
- URL_ROOT: './',
+ URL_ROOT: '',
VERSION: '0.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
@@ -202,7 +202,7 @@
</div>
<div class="footer">
© Copyright 2013, HPL.
- Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2pre.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
=======================================
--- /doc/demos/manual/html/manual.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/manual.html Fri Jun 28 09:22:02 2013
@@ -15,7 +15,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
- URL_ROOT: './',
+ URL_ROOT: '',
VERSION: '0.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
@@ -56,7 +56,7 @@
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Author:</th><td
class="field-body">Hans Petter Langtangen</td>
</tr>
-<tr class="field-even field"><th class="field-name">Date:</th><td
class="field-body">May 29, 2013</td>
+<tr class="field-even field"><th class="field-name">Date:</th><td
class="field-body">Jun 28, 2013</td>
</tr>
</tbody>
</table>
@@ -562,7 +562,7 @@
<div class="section" id="from-doconce-to-other-formats">
<span id="doconce2formats"></span><h1>From Doconce to Other Formats<a
class="headerlink" href="#from-doconce-to-other-formats" title="Permalink
to this headline">¶</a></h1>
<p>Transformation of a Doconce document <tt class="docutils literal"><span
class="pre">mydoc.do.txt</span></tt> to various other
-formats applies the script <tt class="docutils literal"><span
class="pre">doconce</span> <span class="pre">format</span></tt>:</p>
+formats apply the script <tt class="docutils literal"><span
class="pre">doconce</span> <span class="pre">format</span></tt>:</p>
<div class="highlight-console"><div class="highlight"><pre><span
class="go">Terminal> doconce format format mydoc.do.txt</span>
</pre></div>
</div>
@@ -1537,7 +1537,7 @@
part of the caption appearing on the same line as <tt class="docutils
literal"><span class="pre">FIGURE:</span></tt> will be
included in the formatted caption).</p>
<div class="figure" id="fig-viz">
-<a class="reference internal image-reference"
href="_images/streamtubes.png"><img alt="_images/streamtubes.png"
src="_images/streamtubes.png" style="width: 400px;" /></a>
+<img alt="_images/streamtubes.png" src="_images/streamtubes.png"
style="width: 400px;" />
<p class="caption"><em>Streamtube visualization of a fluid flow</em></p>
</div>
<p>Combining several image files into one, in a table fashion, can be done
by the
@@ -1827,7 +1827,7 @@
(the label appears in the figure caption in the source code of this
document).
Additional references to the sections <a class="reference internal"
href="#mathtext"><em>LaTeX Blocks of Mathematical Text</em></a> and <a
class="reference internal" href="#newcommands"><em>Macros
(Newcommands)</em></a> are
nice to demonstrate, as well as a reference to equations,
-say <a href="#equation-myeq1">(1)</a>-<a href="#equation-myeq2">(2)</a>. A
comparison of the output and
+say (<em class="xref std std-ref">myeq1</em>)-(<em class="xref std
std-ref">myeq2</em>). A comparison of the output and
the source of this document illustrates how labels and references
are handled by the format in question.</p>
<p>Hyperlinks to files or web addresses are handled as explained
@@ -1937,7 +1937,10 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).</p>
+LaTeX is the output format). For paragraphs with <tt class="docutils
literal"><span class="pre">===</span></tt> heading,
+the index keywords should be placed above the heading.</p>
+<p>The keywords in the index are automatically placed in a meta
+tag in <tt class="docutils literal"><span class="pre">html</span></tt>
output such that search engines can make use of the them.</p>
</div>
<div class="section" id="bibliography-2">
<h2>Bibliography (2)<a class="headerlink" href="#bibliography-2"
title="Permalink to this headline">¶</a></h2>
@@ -2113,7 +2116,18 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes <tt class="docutils literal"><span class="pre">|
</span></tt> can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
-Note that not all formats offer alignment of heading or entries
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like</p>
+<div class="highlight-text"><div class="highlight"><pre>|
--c--------c-----------c--------|
+|time | velocity | acceleration |
+|--l--------r-----------r--------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------|
+</pre></div>
+</div>
+<p>Note that not all formats offer alignment of heading or entries
in tables (<tt class="docutils literal"><span class="pre">rst</span></tt>
and <tt class="docutils literal"><span class="pre">sphinx</span></tt> are
examples). Also note that
Doconce tables are very simple: neither entries nor
headings can span several columns or rows. When that functionality
@@ -2123,6 +2137,29 @@
makes Doconce dump each table to CSV format in a file <tt class="docutils
literal"><span class="pre">table_X.csv</span></tt>,
where <tt class="docutils literal"><span class="pre">X</span></tt> is the
table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.</p>
+<p>Data in CSV format can be transformed to Doconce table format
+by the <tt class="docutils literal"><span class="pre">doconce</span> <span
class="pre">csv2table</span></tt> utility:</p>
+<div class="highlight-console"><div class="highlight"><pre><span
class="go">Terminal> doconce csv2table somefile.csv >
table.do.txt</span>
+</pre></div>
+</div>
+<p>This is a quick way of writing tables. For example, we can
+write a text file <tt class="docutils literal"><span
class="pre">tmp.csv</span></tt> with</p>
+<div class="highlight-python"><div class="highlight"><pre><span
class="n">time</span><span class="p">,</span> <span
class="n">velocity</span><span class="p">,</span> <span
class="n">acceleration</span>
+<span class="mf">0.0</span><span class="p">,</span> <span
class="mf">1.4186</span><span class="p">,</span> <span
class="o">-</span><span class="mf">5.01</span>
+<span class="mf">2.0</span><span class="p">,</span> <span
class="mf">1.376512</span><span class="p">,</span> <span
class="mf">11.919</span>
+<span class="mf">4.0</span><span class="p">,</span> <span
class="mf">1.1E+1</span><span class="p">,</span> <span
class="mf">14.717624</span>
+</pre></div>
+</div>
+<p>Running <tt class="docutils literal"><span class="pre">doconce</span>
<span class="pre">csv2table</span> <span class="pre">tmp.csv</span></tt>
creates the table</p>
+<div class="highlight-text"><div class="highlight"><pre>|
------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+</pre></div>
+</div>
</div>
<div class="section" id="exercises-problems-projects-and-examples">
<h2>Exercises, Problems, Projects, and Examples<a class="headerlink"
href="#exercises-problems-projects-and-examples" title="Permalink to this
headline">¶</a></h2>
@@ -2377,7 +2414,7 @@
</pre></div>
</div>
<p>And here is a C++ code snippet (<tt class="docutils literal"><span
class="pre">cppcod</span></tt> style):</p>
-<div class="highlight-c++"><div class="highlight"><pre><span
class="kt">void</span> <span class="n">myfunc</span><span
class="p">(</span><span class="kt">double</span><span class="o">*</span>
<span class="n">x</span><span class="p">,</span> <span
class="k">const</span> <span class="kt">double</span><span
class="o">&</span> <span class="n">myarr</span><span class="p">)</span>
<span class="p">{</span>
+<div class="highlight-c++"><div class="highlight"><pre><span
class="kt">void</span> <span class="nf">myfunc</span><span
class="p">(</span><span class="kt">double</span><span class="o">*</span>
<span class="n">x</span><span class="p">,</span> <span
class="k">const</span> <span class="kt">double</span><span
class="o">&</span> <span class="n">myarr</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">for</span> <span class="p">(</span><span
class="kt">int</span> <span class="n">i</span> <span class="o">=</span>
<span class="mi">1</span><span class="p">;</span> <span class="n">i</span>
<span class="o"><</span> <span class="n">myarr</span><span
class="p">.</span><span class="n">size</span><span class="p">();</span>
<span class="n">i</span><span class="o">++</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">myarr</span><span class="p">[</span><span
class="n">i</span><span class="p">]</span> <span class="o">=</span> <span
class="n">myarr</span><span class="p">[</span><span class="n">i</span><span
class="p">]</span> <span class="o">-</span> <span class="n">x</span><span
class="p">[</span><span class="n">i</span><span class="p">]</span><span
class="o">*</span><span class="n">myarr</span><span class="p">[</span><span
class="n">i</span><span class="o">-</span><span class="mi">1</span><span
class="p">]</span>
<span class="p">}</span>
@@ -2485,11 +2522,6 @@
!et
</pre></div>
</div>
-<p>Here is the result:</p>
-<div class="math" id="equation-myeq1">
-<span class="eqno">(1)</span>\[ {\partial u\over\partial t} = \nabla^2
u + f,\]</div>
-<div class="math" id="equation-myeq2">
-<span class="eqno">(2)</span>\[ {\partial v\over\partial t} =
\nabla\cdot(q(u)\nabla v) + g.\]</div>
<p>The support of LaTeX mathematics varies among the formats:</p>
<blockquote>
<div><ul class="simple">
@@ -2579,59 +2611,27 @@
newcommands in the <tt class="docutils literal"><span
class="pre">newcommands*.tex</span></tt> files <em>must</em> appear on a
single
line (multi-line newcommands are too hard to parse with regular
expressions).</p>
-<p><em>Example.</em> Suppose we have the following commands in
-<tt class="docutils literal"><span
class="pre">newcommand_replace.tex</span></tt>:</p>
-<div class="highlight-text"><div
class="highlight"><pre>\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-</pre></div>
-</div>
-<p>and these in <tt class="docutils literal"><span
class="pre">newcommands_keep.tex</span></tt>:</p>
-<div class="highlight-text"><div
class="highlight"><pre>\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-</pre></div>
-</div>
-<p>The LaTeX block</p>
-<div class="highlight-text"><div class="highlight"><pre>\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-</pre></div>
-</div>
-<p>will then be rendered to</p>
-<div class="math">
-\[\begin{split}\pmb{x}\cdot\pmb{n} &= 0, \\
-\frac{D{\vec u}{dt}} &= \pmb{Q} {\thinspace . }\end{split}\]</div>
-<p>in the current format.</p>
</div>
<div class="section" id="admonitions">
<h2>Admonitions<a class="headerlink" href="#admonitions" title="Permalink
to this headline">¶</a></h2>
<p>Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.</p>
<p>The following admonition environments are available:
-<tt class="docutils literal"><span class="pre">block</span></tt>, <tt
class="docutils literal"><span class="pre">warning</span></tt>, <tt
class="docutils literal"><span class="pre">notice</span></tt>, <tt
class="docutils literal"><span class="pre">hint</span></tt>, <tt
class="docutils literal"><span class="pre">question</span></tt>, and <tt
class="docutils literal"><span class="pre">summary</span></tt>.
-The box is defined by begin and end tags such as <tt class="docutils
literal"><span class="pre">!bhint</span></tt> and <tt class="docutils
literal"><span class="pre">!ehint</span></tt>.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading <em>Hint</em> (with number)
-appears, while outside exercises the <tt class="docutils literal"><span
class="pre">hint</span></tt> environment gives a
-box with some admonition icon, text and/or colored background.)
+<tt class="docutils literal"><span class="pre">block</span></tt>, <tt
class="docutils literal"><span class="pre">warning</span></tt>, <tt
class="docutils literal"><span class="pre">notice</span></tt>, <tt
class="docutils literal"><span class="pre">question</span></tt>, and <tt
class="docutils literal"><span class="pre">summary</span></tt>.
+The box is defined by begin and end tags such as <tt class="docutils
literal"><span class="pre">!bnotice</span></tt> and <tt class="docutils
literal"><span class="pre">!enotice</span></tt>.
The title of the box is fully customizable.</p>
<p>Here are a few examples:</p>
<div class="highlight-text"><div class="highlight"><pre>!bwarning
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -2655,7 +2655,7 @@
<p class="first admonition-title">Warning</p>
<p class="last">Here is a warning!</p>
</div>
-<div class="admonition hint">
+<div class="admonition-hint admonition">
<p class="first admonition-title">Hint</p>
<p class="last">This is a hint.</p>
</div>
@@ -3024,7 +3024,8 @@
</div>
<div class="section" id="html5-slides">
<h2>HTML5 Slides<a class="headerlink" href="#html5-slides"
title="Permalink to this headline">¶</a></h2>
-<p>Text is missing... Just a very preliminary sketch of commands:</p>
+<p>Not yet written...</p>
+<p>Just a very preliminary sketch of commands:</p>
<div class="highlight-console"><div class="highlight"><pre><span
class="go">Terminal> doconce format html myslides \</span>
<span class="go"> --pygments_html_style=native
--keep_pygments_html_bg</span>
<span class="go">Terminal> doconce slides_html myslides reveal \</span>
@@ -3045,6 +3046,15 @@
</div>
<div class="section" id="latex-beamer-slides">
<h2>LaTeX Beamer Slides<a class="headerlink" href="#latex-beamer-slides"
title="Permalink to this headline">¶</a></h2>
+<p>Not yet written...</p>
+<div class="section" id="themes">
+<h3>Themes<a class="headerlink" href="#themes" title="Permalink to this
headline">¶</a></h3>
+<p>Four themes come with Doconce: <tt class="docutils literal"><span
class="pre">X_Y</span></tt>, where <tt class="docutils literal"><span
class="pre">X</span></tt> is <tt class="docutils literal"><span
class="pre">blue</span></tt> or <tt class="docutils literal"><span
class="pre">red</span></tt>
+(the main color of the slides) and <tt class="docutils literal"><span
class="pre">Y</span></tt> is <a class="reference external"
href="http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf">plain</a>
+for simple layout and
+<a class="reference external"
href="http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf">shadow</a>
+for shadowed boxes and more visual structure in the slides.</p>
+</div>
</div>
</div>
<div class="section" id="mako-programming">
@@ -3055,6 +3065,15 @@
sufficient for if-else tests to steer which parts of the text that
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Unfortunately, the combination of Mako and LaTeX
mathematics may
+lead to problems because Mako applies syntax like <tt class="docutils
literal"><span class="pre">${var}</span></tt> to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., <tt class="docutils literal"><span
class="pre">${\cal</span> <span class="pre">O}(\Delta</span> <span
class="pre">x^2)$</span></tt> which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.</p>
+</div>
<div class="section" id="the-basics-of-mako">
<h2>The Basics of Mako<a class="headerlink" href="#the-basics-of-mako"
title="Permalink to this headline">¶</a></h2>
<p>Just a preliminary sketch of some Mako code (next example is
better!):</p>
@@ -3222,6 +3241,15 @@
</div>
<div class="section" id="general-problems">
<h2>General Problems<a class="headerlink" href="#general-problems"
title="Permalink to this headline">¶</a></h2>
+<div class="section"
id="spellcheck-reports-a-lot-of-mistakes-related-latex-math">
+<h3>Spellcheck reports a lot of mistakes related LaTeX math<a
class="headerlink"
href="#spellcheck-reports-a-lot-of-mistakes-related-latex-math"
title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">doconce</span> <span
class="pre">spellcheck</span></tt> command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant <tt class="docutils literal"><span
class="pre">tmp_missing_*</span></tt> file and search for the math
expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.</p>
+</div>
<div class="section"
id="doconce-aborts-because-of-a-syntax-error-that-is-not-an-error">
<h3>Doconce aborts because of a syntax error that is not an error<a
class="headerlink"
href="#doconce-aborts-because-of-a-syntax-error-that-is-not-an-error"
title="Permalink to this headline">¶</a></h3>
<p>Doconce searches for typical syntax errors and usually aborts the
@@ -3249,6 +3277,25 @@
</ul>
</div></blockquote>
</div>
+<div class="section"
id="the-mako-preprocessor-claims-a-variable-is-undefined">
+<h3>The Mako preprocessor claims a variable is undefined<a
class="headerlink"
href="#the-mako-preprocessor-claims-a-variable-is-undefined"
title="Permalink to this headline">¶</a></h3>
+<p>Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, <span class="math">\({\cal O}(\Delta x^2)\)</span> is valid
LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use <tt class="docutils literal"><span
class="pre">${</span></tt> anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is <tt class="docutils literal"><span
class="pre">${}^+$</span></tt> type of indication of superscripts.
+A suggested rewrite is <tt class="docutils literal"><span
class="pre">$\,{}^+$</span></tt>.</p>
+<p>The error message will ask you to rerun <tt class="docutils
literal"><span class="pre">doconce</span></tt> with
+<tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt>, which will display the
variable that
+is confusing Mako. However, do not continue to use
+<tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt> while you are debugging
because this
+variable will then always be undefined in that mode.
+Use <tt class="docutils literal"><span class="pre">#</span> <span
class="pre">#ifdef</span></tt> directives to comment out large portions of
+the text and apply a “bisection” procedure to locate where
+the Mako problem is (without <tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt>).</p>
+</div>
<div class="section" id="something-goes-wrong-in-the-preprocessing-step">
<h3>Something goes wrong in the preprocessing step<a class="headerlink"
href="#something-goes-wrong-in-the-preprocessing-step" title="Permalink to
this headline">¶</a></h3>
<p>You can examine <tt class="docutils literal"><span
class="pre">tmp_preprocess__filename</span></tt> and <tt class="docutils
literal"><span class="pre">tmp_mako__filename</span></tt>,
@@ -3623,6 +3670,17 @@
</div>
<div class="section" id="problems-with-html-output">
<h2>Problems with HTML Output<a class="headerlink"
href="#problems-with-html-output" title="Permalink to this
headline">¶</a></h2>
+<div class="section" id="mathjax-formulas-are-not-properly-rendered">
+<h3>MathJax formulas are not properly rendered<a class="headerlink"
href="#mathjax-formulas-are-not-properly-rendered" title="Permalink to this
headline">¶</a></h3>
+<p>Here are some common problems:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Two equations cannot have identical label (this error often arises
+from copying and pasting equations)</li>
+<li><tt class="docutils literal"><span class="pre">[</span></tt> and <tt
class="docutils literal"><span class="pre">]</span></tt> brackets must
sometimes be replaced by <tt class="docutils literal"><span
class="pre">\lbrack</span></tt> and <tt class="docutils literal"><span
class="pre">\rbrack</span></tt></li>
+</ul>
+</div></blockquote>
+</div>
<div class="section" id="how-can-i-change-the-layout-of-the-html-page">
<h3>How can I change the layout of the HTML page?<a class="headerlink"
href="#how-can-i-change-the-layout-of-the-html-page" title="Permalink to
this headline">¶</a></h3>
<p>The easiest way is to edit the HTML style or the HTML code directly.
@@ -3919,7 +3977,10 @@
<li><a class="reference internal" href="#potential-problems">Potential
Problems</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#latex-beamer-slides">LaTeX Beamer
Slides</a></li>
+<li><a class="reference internal" href="#latex-beamer-slides">LaTeX Beamer
Slides</a><ul>
+<li><a class="reference internal" href="#themes">Themes</a></li>
+</ul>
+</li>
</ul>
</li>
<li><a class="reference internal" href="#mako-programming">Mako
Programming</a><ul>
@@ -3930,9 +3991,11 @@
<li><a class="reference internal"
href="#troubleshooting">Troubleshooting</a><ul>
<li><a class="reference internal" href="#disclaimer">Disclaimer</a></li>
<li><a class="reference internal" href="#general-problems">General
Problems</a><ul>
+<li><a class="reference internal"
href="#spellcheck-reports-a-lot-of-mistakes-related-latex-math">Spellcheck
reports a lot of mistakes related LaTeX math</a></li>
<li><a class="reference internal"
href="#doconce-aborts-because-of-a-syntax-error-that-is-not-an-error">Doconce
aborts because of a syntax error that is not an error</a></li>
<li><a class="reference internal"
href="#the-mako-preprocessor-is-seemingly-not-run">The Mako preprocessor is
seemingly not run</a></li>
<li><a class="reference internal"
href="#the-mako-preprocessor-is-fooled-by-doconce-text">The Mako
preprocessor is fooled by Doconce text</a></li>
+<li><a class="reference internal"
href="#the-mako-preprocessor-claims-a-variable-is-undefined">The Mako
preprocessor claims a variable is undefined</a></li>
<li><a class="reference internal"
href="#something-goes-wrong-in-the-preprocessing-step">Something goes wrong
in the preprocessing step</a></li>
<li><a class="reference internal"
href="#figure-captions-are-incomplete">Figure captions are
incomplete</a></li>
<li><a class="reference internal"
href="#preprocessor-directives-do-not-work">Preprocessor directives do not
work</a></li>
@@ -3986,6 +4049,7 @@
</ul>
</li>
<li><a class="reference internal"
href="#problems-with-html-output">Problems with HTML Output</a><ul>
+<li><a class="reference internal"
href="#mathjax-formulas-are-not-properly-rendered">MathJax formulas are not
properly rendered</a></li>
<li><a class="reference internal"
href="#how-can-i-change-the-layout-of-the-html-page">How can I change the
layout of the HTML page?</a></li>
<li><a class="reference internal"
href="#why-do-figures-look-ugly-when-using-html-templates">Why do figures
look ugly when using HTML templates?</a></li>
</ul>
@@ -4040,7 +4104,7 @@
</div>
<div class="footer">
© Copyright 2013, HPL.
- Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2pre.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
=======================================
--- /doc/demos/manual/html/search.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/search.html Fri Jun 28 09:22:02 2013
@@ -15,7 +15,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
- URL_ROOT: './',
+ URL_ROOT: '',
VERSION: '0.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
@@ -94,7 +94,7 @@
</div>
<div class="footer">
© Copyright 2013, HPL.
- Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2pre.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
=======================================
--- /doc/demos/manual/html/searchindex.js Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/searchindex.js Fri Jun 28 09:22:02 2013
@@ -1,1 +1,1 @@
-Search.setIndex({objects:{},terms:{mydoc2:1,linebreak:1,beqa:1,yellow:1,four:1,fig2:1,fig3:1,fig1:1,thinspac:1,consider:1,spellcheck:1,ecollin:1,usepackag:1,matlab:1,under:1,preprocess:[0,1],yourdoc:1,everi:1,wrapper_tech:1,"void":1,theorem_count:1,affect:1,pygments_html_lineno:1,disturb:1,eqnarrai:1,upload:1,vector:1,darkgrai:1,relsiz:1,dirnam:1,direct:1,consequ:1,second:1,esol:1,blue:1,mpeg:1,extra_sect:1,"new":1,net:1,never:1,here:1,"const":1,python_an:1,interpret:1,forum:1,ptex2tex:1,precis:1,loop:1,studi:1,brought:1,unix:1,org:1,outro:1,txt:1,shcod:1,describ:1,would:1,includemovi:1,doconc:[0,1],call:1,recommend:1,calc:1,type:1,pdfcrop:1,relat:1,footerbgcolor:1,notic:1,warn:1,mwk:1,rootdir:1,si2uchh3qim:1,automake_sphinx:1,must:1,springer:1,word:1,setup:1,work:1,split_rst:1,root:1,overrid:1,give:1,da6pap:1,caution:1,want:1,attract:1,end:1,quot:1,ordinari:1,vagrant:1,how:1,answer:1,perspect:1,updat:1,recogn:1,after:1,befor:1,wrong:1,demonstr:1,basicstrap:1,attempt:1,pdfnup:1,bootstrap:1,mwiki:1,neglect:1,myeq1:1,maintain:1,environ:[0,1],eblock:1,enter:1,order:1,srclib:1,deck:1,over:1,becaus:1,jpeg:1,keyboard:1,flexibl:1,vari:1,myfil:1,fit:1,setspac:1,better:1,offic:1,fig:1,comprehens:1,html_style:1,easier:1,miiton:1,them:1,var1:1,thei:1,safe:1,"break":1,yourself:1,choic:1,sphinxext:1,each:1,debug:[0,1],side:1,mean:1,pdflatex:[0,1],laboratori:1,logg:1,extract:1,goe:1,content:[0,1],fairli:1,sphinx_dir:1,reader:1,forth:1,linear:1,navig:1,situat:1,standard:1,acrobat:1,reformul:1,bwarn:1,argument:[0,1],filter:1,iso:1,examples_as_exercis:1,onto:1,no_pygments_html:1,"__theorem":1,rang:1,html_theme_opt:1,render:1,independ:1,biomed:1,restrict:1,instruct:1,alreadi:1,"__abstract":1,primari:1,top:1,sometim:1,mercuri:1,underlin:1,master:1,too:1,similarli:1,toc:1,consol:1,tool:1,xkeyval:1,somewhat:1,knob:1,simula:1,solvin:1,charcter:1,past:1,target:1,keyword:1,provid:1,eq2:1,tree:1,usepack:1,project:[0,1],doonc:1,"5mm":1,admonit:[0,1],fashion:1,dvar1:1,modern:1,raw:1,pylon:1,seen:1,mint:1,minu:1,minted_cpp:1,latter:1,even:1,though:1,pdiff:1,ebook:1,regular:1,letter:1,choos:1,style_vagr:1,tradit:1,don:1,doc:1,flow:1,doe:1,dummi:1,abbrev:1,declar:1,unchang:1,winther:1,random:1,pygments_html_styl:1,syntax:1,mediawiki:1,indentend:1,theme_dir:1,involv:1,layout:1,explain:1,configur:1,theme:1,rich:1,shoutwiki:1,agni:1,watch:1,fluid:1,encourg:1,cloud_spthem:1,makeindex:1,report:1,keyword2:1,keyword1:1,youtub:1,briefer:1,emb:1,"public":1,ban:1,respond:1,exericis:1,kolmogorov:1,pdftool:1,result:1,fail:1,best:1,awar:1,databas:1,wikipedia:1,figur:[0,1],simplest:1,awai:1,approach:1,accord:1,slides_beam:1,extend:1,extens:1,lazi:1,preprocessor:1,extent:1,toler:1,han:1,howev:1,subitem:1,cod:1,docbook:1,seri:1,com:1,mardal:1,dbook:1,height:1,stylefil:1,documentstyl:1,path:1,diff:1,guid:1,assum:1,summar:1,duplic:1,union:1,numpi:1,three:1,been:1,much:1,sphinxdir:1,basic:[0,1],quickli:1,life:1,deeper:1,spit:1,xxy:1,xxx:1,anywher:1,els:1,emploi:1,ugli:1,subentri:1,gnu:1,servic:1,properti:1,sourceforg:1,aim:1,dept:1,aid:1,anchor:1,pyramid:1,coher:1,conv:1,a6pap:1,conf:1,sever:1,mako:[0,1],disabl:1,perform:1,suggest:1,make:1,complex:1,split:[0,1],texinfo:1,complet:1,a2p:1,slides_html:1,mytext:1,hand:1,bibliograph:1,norwegian:1,pngmath_dvipng_arg:1,tune:1,moondist:1,redefin:1,kept:1,thi:1,endif:1,everyth:1,giftran:1,left:1,identifi:1,just:1,rst2odt:1,xelatex:[0,1],human:1,ifdef:1,kdiff3:1,yet:1,languag:[0,1],easi:1,mix:1,interfer:1,fortran:1,cp2texmf:1,save:1,explanatori:1,gave:1,mayb:1,boldfac:1,fromto:1,background:1,shadow:1,wrapfig:1,measur:1,amon:1,specif:1,arbitrari:1,manual:[0,1],docutil:1,www:1,right:1,old:1,intern:1,toctre:1,successfulli:1,total:1,collect:1,univ:1,core:1,plu:1,bold:1,fancyvrb:1,repositori:1,post:[0,1],chapter:1,slightli:1,surround:1,algn:1,"__proof":1,produc:1,ppa:1,"float":1,encod:1,fancybox:1,down:1,wrap:1,accordingli:1,git:1,perldoc:1,suffici:1,support:1,transform:1,why:1,avail:1,width:1,wordpress:1,editor:1,analysi:1,head:1,satisfactorili:1,form:1,offer:1,solar:1,"true":1,featur:[0,1],classic:1,request:1,"abstract":1,ephas:1,postscript:1,exist:1,check:1,assembl:1,somenam:1,tkdiff:1,eremark:1,when:1,test:1,diffpack:1,matur:1,notif:1,intend:1,asterisk:1,consid:1,occasion:1,stoke:1,bitbucket:1,longer:1,bullet:1,phone:1,ignor:1,maxdepth:1,time:1,beamer:[0,1],nxn:1,concept:1,particular:1,row:1,middl:1,depend:[0,1],unnumb:1,flask:1,vec:1,texmf:1,proj:1,sourc:[0,1],xpro:1,brows:1,seemingli:1,level:1,did:1,relbarbgcolor:1,iter:1,item:1,preprocesor:1,combine_imag:1,team:1,quick:[0,1],sidebarlinkcolor:1,round:1,dir:1,sign:1,pmb:1,dmath:1,appear:1,anywai:1,current:1,rst2xml:1,meld:1,xml:1,autogener:1,gener:[0,1],disclaim:[0,1],modif:1,address:1,locat:1,along:1,box:1,shift:1,trial:1,behav:1,myvar:1,slidecel:1,extra:1,tweak:[0,1],modul:[0,1],ipi:1,prefer:1,backtick:1,visibl:1,instal:[0,1],should:1,regex:1,dvipdf:1,univers:1,helvetica:1,todai:1,subvers:1,stylesheet:1,criteria:1,checkout:1,share:1,newcommand:[0,1],visual:1,appendix:1,indic:[0,1],examin:1,easiest:1,dhelvetica:1,slogan:1,uniqu:1,impel:1,can:1,purpos:1,ehint:1,encapsul:1,bloodish:1,backslash:1,topic:1,abort:1,occur:1,alwai:1,differenti:1,multipl:1,oslo:1,no_abort:1,write:[0,1],pure:1,tile:1,ispel:1,map:1,clone:1,codetermin:1,mac:1,mai:1,underscor:1,data:1,man:1,mdframe:1,favorit:1,inform:1,"switch":1,cannot:1,combin:1,ssh:1,epydoc:1,boldface_:1,"_part0000_mydoc":1,equip:1,still:1,mainli:1,dynam:1,entiti:1,group:1,passag:1,platform:1,window:1,doconce_head:1,main:1,non:1,recal:1,matcher:1,initi:1,half:1,now:1,discuss:1,nor:1,name:1,config:1,separ:1,mydoc_html_file_collect:1,admon:1,compil:1,f2f2f2:1,replac:1,individu:1,continu:1,backport:1,year:1,happen:1,reportlab:1,space:1,bnotic:1,sespecif:1,formula:1,md2html:1,correct:1,headlin:1,fontsiz:1,institut:1,care:1,"__a":1,wai:1,modest:1,thing:1,place:1,view:1,nicknam:1,imposs:1,frequent:1,first:1,origin:1,directli:1,carri:1,onc:1,arrai:1,bluish:1,lsb_releas:1,fast:1,open:1,predefin:1,size:1,given:1,xunicod:1,sheet:1,convent:1,gif:1,white:1,conveni:1,cite:1,forthcom:1,especi:1,copi:[0,1],bsubex:1,specifi:1,"short":1,enclos:1,than:1,png:1,wide:1,instanc:1,posit:1,zsh:1,browser:1,pre:1,unoconv:1,sai:1,nicer:1,pro:1,svnroot:1,ani:1,dash:1,zumbusch:1,mislead:1,engin:1,squar:1,destroi:1,moreov:1,note:[0,1],myeq2:1,take:1,includegraph:1,begin:1,sure:1,normal:1,track:1,fix_bibtex4publish:1,pair:1,icon:1,latex:[0,1],later:1,typeset:[0,1],preambl:1,main_myproj:1,viscou:1,show:1,scitool:1,bright:1,corner:1,unfinish:1,slot:1,onli:1,activ:1,analyz:1,microtyp:1,overwritten:1,variou:1,get:1,xcod:1,tailor:1,springer_collect:1,requir:1,reveal:1,tikz:1,cppcod:1,seldom:1,rst2pdf:1,paper:1,next1:1,where:1,summari:1,wiki:[0,1],"_sever":1,detect:1,xetex:1,label:1,enough:1,between:1,"import":1,inputenc:1,parent:1,screen:1,come:1,tug:1,img:1,tutori:1,mani:1,fix:1,among:1,acceler:1,color:1,overview:[0,1],inspir:1,period:1,pop:1,colon:1,typic:1,ultim:1,segfault:1,mark:1,structuredtext:1,encapusl:1,emphas:1,resolut:1,f90:1,f95:1,impati:1,former:1,those:1,"case":1,thesi:1,invok:1,advantag:1,ctrl:1,henc:1,destin:1,eras:1,ascii:[0,1],pdftk:1,develop:1,author:1,media:1,same:1,html:[0,1],document:[0,1],equat:1,nest:1,assist:1,extern:1,mycount:1,appropri:1,inconsist:1,macro:[0,1],markup:[0,1],ccq:1,sreen:1,without:1,kaar:1,venu:1,execut:1,documentclass:1,rest:[0,1],without_solut:1,flavor:1,hint:1,except:1,littl:1,blog:[0,1],treatment:1,exercis:[0,1],real:1,around:1,read:1,swig:1,nonnest:1,dark:1,grid:1,envir:1,world:1,mydict:1,whitespac:1,cdot:1,inted:1,integ:1,either:1,"_static":1,output:[0,1],fulfil:1,normalvec:1,thpack:1,palatino:1,shadowbox:1,constitut:1,definit:1,legal:1,ddt:1,subproblem:1,exit:1,refer:[0,1],power:1,inspect:1,tables2csv:1,fulli:1,regexp:1,src:1,split_html:1,stand:1,act:1,mytempl:1,dtodonot:1,myroutin:1,fundamental1:1,pagebreak:1,yyi:1,your:1,wikibook:1,log:1,her:1,area:1,haskel:1,start:1,lot:1,verbatim:[0,1],bundl:1,streamtub:1,diffus:1,blueish:1,untag:1,pull:1,possibl:1,"default":1,plaympeg:1,creol:1,externaldocu:1,xcolor:1,creat:1,certain:1,strongli:1,intro:1,decreas:1,file:[0,1],again:1,googl:1,valid:1,you:1,condens:1,sequenc:1,symbol:1,langtangen_et_al_2002:1,sidebartextcolor:1,includemedia:1,exerinfo:1,tmp_mako__filenam:1,unbalanc:1,backward:1,directori:1,descript:[0,1],potenti:1,cpp:1,escap:1,all:1,forget:1,illustr:1,dollar:1,"___sec2":1,follow:1,alt:1,external_movie_view:1,iconv:1,articl:1,program:[0,1],introduc:1,straightforward:1,fals:1,helvet:1,util:1,"1px":1,verb:1,mechan:1,texconv:1,veri:1,strang:1,unalt:1,nileshbans:1,list:[0,1],adjust:1,plain:[0,1],small:1,dxelatex:1,tex:[0,1],design:1,pass:1,further:1,what:[0,1],sub:1,section:1,netpbm:1,delet:1,version:1,method:1,full:1,hash:1,verbatim_text:1,sophist:1,behaviour:1,trunk:1,strong:1,modifi:1,valu:[0,1],search:[0,1],newlin:1,prior:1,amount:1,pick:1,action:1,narrow:1,via:1,depart:1,rightsidebar:1,filenam:1,href:1,html_theme:1,proceed:1,two:1,formul:1,taken:1,more:1,diamond:1,desir:1,ital:1,dnote:1,flag:1,stick:1,aris:1,known:1,shkumagai:1,none:1,valuabl:1,outlin:1,histori:1,paragraph:1,learn:1,rst2html:1,def:1,uncom:1,inline_tag_begin:1,dexternal_movie_view:1,accept:1,phrase:1,string:1,cours:1,csh:1,divid:1,rather:1,anoth:1,spreadsheet:1,snippet:1,csv:1,simpl:1,css:1,agogo:1,resourc:1,referenc:[0,1],variant:1,"_text":1,fignam:1,wave:1,associ:1,github:1,md2latex:1,footer:[0,1],confus:1,caus:1,testdoc:1,egg:1,help:1,devhelp:1,soon:1,scientist:1,through:1,myarr:1,paramet:1,style:1,roemer:1,ptext2tex:1,amsfont:1,gwiki:[0,1],might:1,fool:1,recip:1,good:1,"return":[0,1],sentenc:1,sphinxfix_localurl:1,petter:1,parenthesi:1,epsfig:1,troubleshoot:[0,1],easili:1,achiev:1,fpro:1,found:1,dir2:1,dir1:1,maketitl:1,sidebarbgcolor:1,hard:1,idea:[0,1],procedur:1,realli:1,heavi:1,beyond:1,"_part":1,publish:1,research:1,footnot:1,lineno:1,print:1,subsubsect:1,my_fil:1,advanc:1,pub:1,ref4:1,reason:1,base:1,put:1,teach:1,bash:1,launch:1,veloc:1,script:1,dpalatino:1,caption:1,perhap:1,fcod:1,ubuntuforum:1,major:1,feel:1,famou:1,misc:1,number:1,unovonv:1,smaller:[0,1],done:1,construct:1,blank:1,miss:[0,1],fanci:1,differ:[0,1],pandoc:[0,1],without_answ:1,cpp_an:1,interact:1,least:1,latexdiff:1,statement:1,natur:1,illeg:1,scheme:1,evinc:1,option:1,part:1,pars:[0,1],myclass:1,kind:1,ffmpeg:1,whenev:1,remov:[0,1],bibliographystyl:1,horizont:1,reus:1,store:1,sty:1,cleaner:1,comput:[0,1],packag:1,anslist:1,built:1,self:1,also:1,institution2:1,institution3:1,institution1:1,distribut:1,previou:1,reach:1,most:1,plai:1,exer:1,destruct:1,ext:1,clean:1,microsoft:1,think:1,sublist:1,diffpdf:1,session:1,particularli:1,font:1,fine:1,find:1,auctex:1,impact:1,mwlib:1,mjolnir:1,writer:1,solut:1,templat:1,smtplib:1,remedi:1,express:1,nativ:1,libreoffic:1,eq1:1,common:1,set:1,dump:1,creator:1,see:1,sed:1,close:1,someth:1,mybibtexfil:1,no_preprocess:1,subdir:1,experi:1,birkenfeld:1,altern:1,impressj:1,imagemagick:1,numer:1,javascript:1,subexercis:1,ipython:1,water:1,last:1,delimit:1,hyperlink:1,alon:1,"_part0001_mydoc":1,context:1,forgotten:1,pdf:1,whole:1,load:1,markdown:[0,1],simpli:1,point:1,header:[0,1],pycod:1,linux:1,throughout:1,becom:1,java:1,devic:1,due:1,empti:1,newcommands_replac:1,eart2moon_sol:1,strategi:1,invis:1,imag:1,remark:1,epytext:1,understand:1,demand:1,look:1,bluish2:1,formatt:[0,1],"while":1,smart:1,abov:1,error:1,subsitut:1,vlinux:1,pack:1,subsect:1,propag:1,html_admon:1,readi:1,itself:1,rid:1,minim:1,shorter:1,archiv:1,myslid:1,esubex:1,alert:1,user:1,cwiki:1,recent:1,lower:1,task:1,entri:1,elev:1,propos:1,explan:1,langtangen:1,restructuredtext:[0,1],shortcut:1,informat:1,theorem:[0,1],input:1,subroutin:1,format:[0,1],big:1,bib:1,backquot:1,table2:1,table3:1,semi:1,brace:1,xxdiff:1,resolv:1,"_part0002_mydoc":1,popular:1,ignorn:1,encount:1,sketch:1,often:1,simplifi:1,creation:1,some:1,back:1,understood:1,scale:1,montag:1,per:1,substitut:1,mathemat:[0,1],larg:1,retro:1,prog:1,object:1,run:1,zzz:1,newcommand_replac:1,step:[0,1],qthelp:1,idx:1,materi:1,idl:1,incompress:1,langtangen_2003a:1,block:[0,1],file3:1,file2:1,file1:1,doubl:1,emphasi:1,file4:1,within:1,ensur:1,perl:1,occupi:1,inclus:1,mkd:1,span:1,question:1,nosidebar:1,textual:1,custom:1,guess_encod:1,subst:1,includ:1,suit:1,myfunc:1,properli:1,link:1,translat:1,newer:1,line:[0,1],listtyp:1,concaten:1,latex_preambl:1,utf:1,consist:1,inline_tag:1,apricot:1,access:1,someus:1,"export":1,similar:1,knob_left:1,repres:1,incomplet:1,home:1,curl:1,titl:1,invalid:1,bibfil:1,bracket:1,prev1:1,newcommands_keep:1,nice:1,mathpazo:1,colored_table_row:1,svn:1,rst2latex:1,bsummari:1,depth:1,far:1,code:[0,1],partial:1,totem:1,rtf:1,makeidx:1,moon:1,refs3:1,refs2:1,refs1:1,compact:1,cython:1,showthread:1,elsewher:1,send:1,becam:1,sens:1,fenics_minim:1,docoment:1,titlepag:1,makotempl:1,volum:1,untouch:1,relev:1,tri:1,"20435c":1,button:1,ryan:1,"try":1,impli:1,exted:1,cfg:1,odt:1,jump:1,video:1,haiku:1,download:1,click:1,index:[0,1],femdeq:1,compar:1,resembl:1,multimedia:1,cell:1,experiment:1,remove_inline_com:1,mathjax:1,tveito:1,deduc:1,whatev:1,vibrat:1,bibitem:1,matplotlib:1,html_fenic:1,bodi:1,let:1,dmovie15:1,ubuntu:[0,1],vertic:1,sinc:1,convert:1,convers:1,larger:1,chang:1,problemat:1,chanc:1,firefox:1,appli:1,colors1:1,apt:1,cloud:1,from:[0,1],live:1,mydir:1,next:1,websit:1,few:1,postprocess:1,sort:1,slim:1,comparison:1,trail:1,langtangen_pedersen_2002:1,retriev:1,annoi:1,column:1,obvious:1,meet:1,proof:1,control:1,quickstart:1,process:1,sudo:1,blue_section_head:1,tag:[0,1],doconce_install_al:1,tarbal:1,surfac:1,subdirectori:1,instead:1,sin:1,yellowish:1,frac:1,stop:1,mypack:1,earth2moon:1,exemplifi:1,keep_pygments_html_bg:1,colors2:1,essenti:1,light:1,counter:1,correspond:1,element:1,issu:1,epstopdf:1,allow:1,dmint:1,elif:1,movi:[0,1],move:1,comma:1,libav:1,myprog:1,outer:1,latex_head:1,chosen:1,therefor:1,docx:1,crash:1,python:1,handi:1,dat:1,mention:1,textopc:1,somewher:1,inline_tag_end:1,edit:1,wdiff:1,uvec:1,slide:[0,1],mode:1,mystyl:1,"10pt":1,pygment:1,subset:1,intellig:1,subsec:1,our:1,special:[0,1],out:1,variabl:[0,1],matrix:1,esummari:1,sandbox:1,texliv:1,suitabl:1,rel:1,ref:1,math:1,statist:1,insid:1,manipul:1,standalon:1,dictionari:1,pedersen:1,indent:1,could:1,ask:1,movie15:1,keep:1,length:1,outsid:1,navier:1,geometri:1,cyberspac:1,softwar:1,manuscript:1,blogger:1,texshop:1,date:1,"long":1,mkdir:1,system:1,messag:1,termin:1,siam:1,"final":1,shell:1,bhint:1,bblock:1,cyb:1,rst:1,newtheorem:1,exactli:1,myfram:1,structur:1,charact:1,steer:1,viewer:1,explicit:1,have:1,tabl:[0,1],need:1,turn:1,border:1,table4:1,minted_python:1,preced:1,which:1,divers:1,singl:1,unless:1,preliminari:1,who:1,ooxml:1,awl:1,mplayer:1,twitter_bootstrap:1,segment:1,"class":1,epub:1,"_build":1,todonot:1,latin1:1,url:1,hardcod:1,face:1,pipe:1,bibtex:1,determin:1,ubuntu_vers:1,fact:1,smpeg:1,text:[0,1],skip_inline_com:1,knob_forward:1,blognam:1,graybox1:1,graybox2:1,graybox3:1,thicker:1,emac:[0,1],titlesec:1,html_templat:1,dispers:1,jal:1,"_mydoc":1,suppos:1,conclus:1,local:1,ksh:1,meant:1,mythem:1,contribut:1,familiar:1,autom:1,table_x:1,pressbook:1,enabl:1,theorem_fundamental1:1,ewarn:1,grai:1,blogspot:1,integr:1,contain:1,typset:1,end1:1,frame:1,"_doconce_debug":1,incoveni:1,pngmath:1,correctli:1,boundari:1,written:1,hyperbaseurl:1,neither:1,email:1,kei:1,job:1,entir:1,exclam:1,embed:1,addit:1,hyperref:1,nabla:1,equal:1,thereaft:1,etc:1,eta:1,html_slide_them:1,html5:[0,1],comment:[0,1],cxx:1,guidelin:1,distinguish:1,respect:1,ifthen:1,quit:1,mjpegtool:1,blueish2:1,m2html:1,json:1,treat:1,curli:1,both:1,split_:1,bremark:1,media9:1,togeth:1,graphicx:1,present:1,multi:1,eeqa:1,vimeo:1,align:1,defin:[0,1],customiz:1,almost:1,demo:[0,1],texttt:1,site:1,change_encod:1,simulate_and_plot:1,revis:1,scienc:1,satisfi:1,cross:[0,1],handl:1,html_pyramid:1,template_vagr:1,mydoc:1,inc:1,difficult:1,http:1,ref1:1,expans:1,ref3:1,ref2:1,ref5:1,effect:1,a4pap:1,redcloud:1,logfil:1,php:1,expand:1,off:1,center:1,openofficeword:1,nevertheless:1,well:1,difflib:1,autoplai:1,exampl:[0,1],command:1,english:1,undefin:1,usual:1,distanc:1,less:1,obtain:1,tcl:1,fenic:1,web:1,makefil:[0,1],add:1,other:[0,1],bibliographi:[0,1],match:1,dextra_sect:1,css3:1,rememb:1,hpl:1,piec:[0,1],realiz:1,know:1,tick:1,testm:1,insert:1,resid:1,like:1,success:1,unord:1,necessari:1,dlatex_head:1,page:[0,1],"11px":1,underscror:1,captur:1,suppli:1,python_anst:1,scipy_lectur:1,latex_print:1,proper:1,guarante:1,lead:1,avoid:1,yellowbox:1,leav:1,newfil:1,speak:1,mathmpl:1,investig:1,journal:1,usag:1,host:1,encourav:1,although:1,simpler:1,about:1,actual:1,rst2:1,linenumb:1,powerpoint:1,own:1,amsmath:1,automat:1,bsol:1,merg:1,citat:1,pictur:1,trigger:1,"var":1,"function":[0,1],multigrid:1,unexpect:1,ean:1,overflow:1,inlin:[0,1],bug:1,count:1,made:1,wise:1,wish:1,googlecod:1,displai:1,troubl:1,below:1,limit:1,otherwis:1,problem:[0,1],"int":1,dure:1,tmp_preprocess__filenam:1,enotic:1,novemb:1,implement:1,pip:1,sphinxjp:1,probabl:1,detail:1,book:1,bool:1,futur:1,branch:1,varieti:1,fontspec:1,repeat:1,shown:1,no_mako:1,debian:[0,1],sphinx:[0,1],eof:1,scientif:1,rule:1,portion:1,openoffic:1,f77:1},objtypes:{},titles:["Doconce
Manual","Doconce
Description"],objnames:{},filenames:["index","manual"]})
+Search.setIndex({objects:{},terms:{mydoc2:1,linebreak:1,yellow:1,four:1,fig2:1,fig3:1,fig1:1,consider:1,spellcheck:1,ecollin:1,usepackag:1,matlab:1,under:1,preprocess:[0,1],yourdoc:1,everi:1,wrapper_tech:1,"void":1,rise:1,theorem_count:1,affect:1,pygments_html_lineno:1,disturb:1,upload:1,vector:1,math:1,darkgrai:1,relsiz:1,dirnam:1,direct:1,consequ:1,second:1,esol:1,blue:1,mpeg:1,extra_sect:1,"new":1,net:1,never:1,here:1,"const":1,python_an:1,interpret:1,forum:1,ptex2tex:1,precis:1,loop:1,studi:1,brought:1,unix:1,org:1,outro:1,txt:1,shcod:1,describ:1,would:1,includemovi:1,doconc:[0,1],call:1,typo:1,recommend:1,calc:1,type:1,pdfcrop:1,relat:1,footerbgcolor:1,notic:1,warn:1,mwk:1,rootdir:1,si2uchh3qim:1,automake_sphinx:1,must:1,springer:1,word:1,setup:1,work:1,split_rst:1,root:1,overrid:1,give:1,da6pap:1,somefil:1,caution:1,want:1,attract:1,end:1,quot:1,ordinari:1,vagrant:1,how:1,answer:1,perspect:1,updat:1,recogn:1,after:1,befor:1,wrong:1,demonstr:1,basicstrap:1,attempt:1,pdfnup:1,bootstrap:1,mwiki:1,neglect:1,myeq1:1,maintain:1,environ:[0,1],eblock:1,enter:1,order:1,srclib:1,deck:1,over:1,becaus:1,jpeg:1,keyboard:1,flexibl:1,vari:1,myfil:1,fit:1,setspac:1,better:1,offic:1,fig:1,comprehens:1,html_style:1,easier:1,miiton:1,them:1,var1:1,thei:1,safe:1,"break":1,yourself:1,choic:1,sphinxext:1,each:1,debug:[0,1],side:1,mean:1,pdflatex:[0,1],laboratori:1,logg:1,extract:1,goe:1,content:[0,1],rewrit:1,fairli:1,sphinx_dir:1,reader:1,forth:1,linear:1,navig:1,situat:1,standard:1,acrobat:1,reformul:1,bwarn:1,argument:[0,1],filter:1,iso:1,examples_as_exercis:1,onto:1,no_pygments_html:1,"__theorem":1,rang:1,html_theme_opt:1,render:1,independ:1,biomed:1,restrict:1,instruct:1,alreadi:1,"__abstract":1,primari:1,top:1,sometim:1,mercuri:1,underlin:1,master:1,too:1,similarli:1,toc:1,consol:1,tool:1,xkeyval:1,somewhat:1,knob:1,simula:1,solvin:1,charcter:1,past:1,target:1,keyword:1,provid:1,tree:1,usepack:1,project:[0,1],doonc:1,"5mm":1,admonit:[0,1],fashion:1,dvar1:1,modern:1,raw:1,pylon:1,seen:1,mint:1,minu:1,minted_cpp:1,latter:1,even:1,though:1,pdiff:1,ebook:1,regular:1,letter:1,choos:1,style_vagr:1,tradit:1,don:1,doc:1,flow:1,doe:1,dummi:1,abbrev:1,declar:1,unchang:1,winther:1,random:1,pygments_html_styl:1,syntax:1,mediawiki:1,indentend:1,theme_dir:1,involv:1,layout:1,explain:1,configur:1,theme:1,rich:1,shoutwiki:1,agni:1,watch:1,fluid:1,encourg:1,cloud_spthem:1,makeindex:1,report:1,keyword2:1,keyword1:1,youtub:1,briefer:1,emb:1,"public":1,ban:1,respond:1,kolmogorov:1,pdftool:1,result:1,fail:1,best:1,awar:1,databas:1,wikipedia:1,figur:[0,1],simplest:1,awai:1,approach:1,accord:1,slides_beam:1,extend:1,extens:1,lazi:1,preprocessor:1,extent:1,toler:1,han:1,howev:1,subitem:1,cod:1,docbook:1,seri:1,com:1,mardal:1,dbook:1,height:1,stylefil:1,documentstyl:1,path:1,diff:1,guid:1,assum:1,summar:1,duplic:1,union:1,numpi:1,three:1,been:1,much:1,sphinxdir:1,basic:[0,1],futur:1,quickli:1,life:1,deeper:1,spit:1,xxy:1,xxx:1,anywher:1,els:1,emploi:1,ugli:1,ident:1,subentri:1,gnu:1,servic:1,properti:1,sourceforg:1,aim:1,dept:1,aid:1,anchor:1,pyramid:1,coher:1,conv:1,a6pap:1,conf:1,sever:1,mako:[0,1],disabl:1,perform:1,suggest:1,make:1,complex:1,split:[0,1],texinfo:1,complet:1,a2p:1,slides_html:1,mytext:1,hand:1,bibliograph:1,norwegian:1,pngmath_dvipng_arg:1,tune:1,moondist:1,redefin:1,kept:1,undesir:1,thi:1,endif:1,everyth:1,giftran:1,left:1,identifi:1,just:1,rst2odt:1,xelatex:[0,1],human:1,ifdef:1,kdiff3:1,yet:1,languag:[0,1],easi:1,mix:1,interfer:1,fortran:1,cp2texmf:1,save:1,explanatori:1,gave:1,mayb:1,boldfac:1,fromto:1,background:1,shadow:1,wrapfig:1,measur:1,amon:1,specif:1,arbitrari:1,manual:[0,1],docutil:1,www:1,right:1,old:1,intern:1,toctre:1,successfulli:1,total:1,collect:1,univ:1,core:1,plu:1,bold:1,fancyvrb:1,repositori:1,post:[0,1],chapter:1,slightli:1,surround:1,unfortun:1,algn:1,"__proof":1,produc:1,ppa:1,"float":1,encod:1,fancybox:1,down:1,wrap:1,accordingli:1,git:1,perldoc:1,suffici:1,support:1,transform:1,why:1,avail:1,width:1,wordpress:1,editor:1,analysi:1,head:1,satisfactorili:1,form:1,offer:1,solar:1,"true":1,rerun:1,featur:[0,1],classic:1,request:1,"abstract":1,ephas:1,postscript:1,exist:1,check:1,assembl:1,somenam:1,tkdiff:1,eremark:1,when:1,test:1,diffpack:1,matur:1,notif:1,intend:1,asterisk:1,consid:1,occasion:1,stoke:1,bitbucket:1,longer:1,bullet:1,phone:1,ignor:1,maxdepth:1,time:1,beamer:[0,1],nxn:1,concept:1,particular:1,row:1,middl:1,depend:[0,1],unnumb:1,flask:1,texmf:1,proj:1,sourc:[0,1],xpro:1,brows:1,seemingli:1,level:1,did:1,relbarbgcolor:1,iter:1,item:1,preprocesor:1,combine_imag:1,team:1,quick:[0,1],sidebarlinkcolor:1,round:1,dir:1,sign:1,dmath:1,appear:1,anywai:1,current:1,rst2xml:1,meld:1,xml:1,autogener:1,gener:[0,1],disclaim:[0,1],modif:1,address:1,locat:1,along:1,box:1,shift:1,trial:1,behav:1,myvar:1,slidecel:1,extra:1,tweak:[0,1],modul:[0,1],ipi:1,prefer:1,backtick:1,visibl:1,instal:[0,1],should:1,regex:1,dvipdf:1,univers:1,helvetica:1,todai:1,subvers:1,stylesheet:1,criteria:1,checkout:1,share:1,newcommand:[0,1],visual:1,appendix:1,indic:[0,1],examin:1,easiest:1,dhelvetica:1,slogan:1,uniqu:1,impel:1,can:1,cal:1,purpos:1,ehint:1,claim:1,encapsul:1,bloodish:1,backslash:1,topic:1,abort:1,occur:1,alwai:1,differenti:1,multipl:1,oslo:1,no_abort:1,write:[0,1],pure:1,tile:1,ispel:1,map:1,clone:1,codetermin:1,mac:1,mai:1,underscor:1,data:1,man:1,mdframe:1,favorit:1,inform:1,"switch":1,cannot:1,combin:1,ssh:1,epydoc:1,boldface_:1,"_part0000_mydoc":1,equip:1,still:1,mainli:1,dynam:1,entiti:1,group:1,passag:1,platform:1,window:1,doconce_head:1,main:1,non:1,recal:1,matcher:1,initi:1,half:1,now:1,discuss:1,nor:1,name:1,config:1,separ:1,mydoc_html_file_collect:1,admon:1,compil:1,f2f2f2:1,replac:1,individu:1,continu:1,backport:1,year:1,happen:1,reportlab:1,space:1,bnotic:1,sespecif:1,formula:1,md2html:1,correct:1,headlin:1,fontsiz:1,mako_strict_undefin:1,institut:1,care:1,"__a":1,wai:1,modest:1,thing:1,place:1,view:1,nicknam:1,imposs:1,frequent:1,first:1,origin:1,directli:1,carri:1,onc:1,arrai:1,bluish:1,lsb_releas:1,fast:1,open:1,predefin:1,size:1,given:1,xunicod:1,sheet:1,convent:1,gif:1,white:1,conveni:1,cite:1,forthcom:1,especi:1,copi:[0,1],bsubex:1,specifi:1,"short":1,enclos:1,than:1,png:1,wide:1,instanc:1,posit:1,zsh:1,browser:1,pre:1,unoconv:1,sai:1,nicer:1,pro:1,svnroot:1,ani:1,dash:1,zumbusch:1,mislead:1,engin:1,squar:1,destroi:1,moreov:1,note:[0,1],myeq2:1,take:1,includegraph:1,begin:1,sure:1,normal:1,track:1,fix_bibtex4publish:1,pair:1,icon:1,latex:[0,1],later:1,typeset:[0,1],preambl:1,main_myproj:1,viscou:1,show:1,scitool:1,bright:1,corner:1,unfinish:1,slot:1,onli:1,activ:1,analyz:1,microtyp:1,overwritten:1,variou:1,get:1,xcod:1,tailor:1,springer_collect:1,requir:1,reveal:1,tikz:1,cppcod:1,seldom:1,rst2pdf:1,paper:1,next1:1,where:1,summari:1,wiki:[0,1],"_sever":1,detect:1,xetex:1,label:1,enough:1,between:1,"import":1,inputenc:1,parent:1,screen:1,come:1,tug:1,img:1,tutori:1,mani:1,fix:1,among:1,acceler:1,color:1,overview:[0,1],inspir:1,period:1,pop:1,colon:1,typic:1,ultim:1,segfault:1,mark:1,structuredtext:1,encapusl:1,emphas:1,resolut:1,f90:1,f95:1,impati:1,former:1,those:1,"case":1,thesi:1,invok:1,advantag:1,ctrl:1,henc:1,destin:1,eras:1,ascii:[0,1],pdftk:1,develop:1,author:1,media:1,same:1,html:[0,1],document:[0,1],equat:1,nest:1,assist:1,extern:1,mycount:1,appropri:1,inconsist:1,macro:[0,1],markup:[0,1],ccq:1,sreen:1,without:1,kaar:1,venu:1,execut:1,documentclass:1,rest:[0,1],without_solut:1,flavor:1,hint:1,except:1,littl:1,blog:[0,1],treatment:1,exercis:[0,1],real:1,around:1,read:1,swig:1,nonnest:1,dark:1,grid:1,envir:1,world:1,mydict:1,whitespac:1,cdot:1,inted:1,integ:1,either:1,"_static":1,output:[0,1],fulfil:1,thpack:1,palatino:1,shadowbox:1,constitut:1,definit:1,legal:1,moon:1,subproblem:1,exit:1,refer:[0,1],power:1,inspect:1,tables2csv:1,fulli:1,regexp:1,src:1,split_html:1,stand:1,act:1,mytempl:1,dtodonot:1,myroutin:1,fundamental1:1,pagebreak:1,yyi:1,your:1,wikibook:1,log:1,her:1,area:1,haskel:1,start:1,lot:1,verbatim:[0,1],bundl:1,jun:1,streamtub:1,diffus:1,blueish:1,untag:1,pull:1,possibl:1,"default":1,plaympeg:1,creol:1,externaldocu:1,xcolor:1,creat:1,certain:1,strongli:1,intro:1,decreas:1,file:[0,1],again:1,googl:1,valid:1,you:1,condens:1,sequenc:1,symbol:1,langtangen_et_al_2002:1,sidebartextcolor:1,includemedia:1,exerinfo:1,tmp_mako__filenam:1,unbalanc:1,backward:1,directori:1,descript:[0,1],lbrack:1,potenti:1,cpp:1,escap:1,all:1,forget:1,illustr:1,dollar:1,"___sec2":1,follow:1,alt:1,external_movie_view:1,iconv:1,articl:1,program:[0,1],introduc:1,straightforward:1,fals:1,helvet:1,util:1,"1px":1,verb:1,mechan:1,texconv:1,veri:1,strang:1,unalt:1,nileshbans:1,list:[0,1],adjust:1,plain:[0,1],small:1,dxelatex:1,tex:[0,1],design:1,pass:1,further:1,what:[0,1],sub:1,section:1,netpbm:1,delet:1,version:1,method:1,full:1,hash:1,verbatim_text:1,misspel:1,sophist:1,behaviour:1,trunk:1,strong:1,modifi:1,valu:[0,1],search:[0,1],newlin:1,prior:1,amount:1,pick:1,action:1,narrow:1,via:1,depart:1,rightsidebar:1,filenam:1,href:1,html_theme:1,proceed:1,two:1,formul:1,taken:1,more:1,diamond:1,desir:1,ital:1,dnote:1,flag:1,stick:1,aris:1,known:1,shkumagai:1,none:1,valuabl:1,outlin:1,histori:1,paragraph:1,learn:1,rst2html:1,def:1,uncom:1,inline_tag_begin:1,dexternal_movie_view:1,accept:1,phrase:1,string:1,cours:1,csh:1,divid:1,rather:1,anoth:1,spreadsheet:1,snippet:1,csv:1,simpl:1,css:1,agogo:1,resourc:1,referenc:[0,1],variant:1,"_text":1,fignam:1,wave:1,associ:1,github:1,md2latex:1,footer:[0,1],confus:1,caus:1,testdoc:1,egg:1,help:1,devhelp:1,soon:1,scientist:1,through:1,myarr:1,paramet:1,style:1,roemer:1,ptext2tex:1,amsfont:1,gwiki:[0,1],might:1,fool:1,recip:1,good:1,"return":[0,1],sentenc:1,sphinxfix_localurl:1,petter:1,parenthesi:1,epsfig:1,troubleshoot:[0,1],easili:1,achiev:1,fpro:1,found:1,dir2:1,dir1:1,maketitl:1,sidebarbgcolor:1,hard:1,idea:[0,1],procedur:1,realli:1,heavi:1,beyond:1,"_part":1,publish:1,research:1,footnot:1,lineno:1,print:1,subsubsect:1,my_fil:1,advanc:1,pub:1,ref4:1,reason:1,base:1,put:1,teach:1,bash:1,launch:1,veloc:1,script:1,dpalatino:1,caption:1,perhap:1,fcod:1,ubuntuforum:1,major:1,feel:1,famou:1,misc:1,number:1,unovonv:1,smaller:[0,1],done:1,construct:1,blank:1,miss:[0,1],fanci:1,differ:[0,1],pandoc:[0,1],without_answ:1,cpp_an:1,interact:1,least:1,latexdiff:1,statement:1,cfg:1,illeg:1,scheme:1,evinc:1,option:1,part:1,pars:[0,1],myclass:1,kind:1,ffmpeg:1,whenev:1,remov:[0,1],bibliographystyl:1,horizont:1,reus:1,store:1,sty:1,cleaner:1,comput:[0,1],packag:1,anslist:1,built:1,self:1,also:1,institution2:1,institution3:1,institution1:1,distribut:1,csv2tabl:1,previou:1,reach:1,most:1,plai:1,exer:1,destruct:1,ext:1,clean:1,microsoft:1,think:1,sublist:1,diffpdf:1,session:1,particularli:1,font:1,fine:1,find:1,auctex:1,impact:1,mwlib:1,mjolnir:1,writer:1,solut:1,templat:1,smtplib:1,remedi:1,express:1,nativ:1,libreoffic:1,eq1:1,common:1,set:1,dump:1,creator:1,see:1,sed:1,close:1,someth:1,mybibtexfil:1,no_preprocess:1,subdir:1,experi:1,birkenfeld:1,altern:1,impressj:1,imagemagick:1,numer:1,javascript:1,subexercis:1,ipython:1,water:1,last:1,delimit:1,hyperlink:1,alon:1,"_part0001_mydoc":1,context:1,forgotten:1,pdf:1,whole:1,load:1,markdown:[0,1],simpli:1,point:1,header:[0,1],pycod:1,linux:1,mistak:1,throughout:1,becom:1,java:1,devic:1,due:1,empti:1,newcommands_replac:1,eart2moon_sol:1,strategi:1,invis:1,imag:1,remark:1,epytext:1,understand:1,demand:1,look:1,bluish2:1,formatt:[0,1],"while":1,smart:1,abov:1,error:1,subsitut:1,vlinux:1,pack:1,subsect:1,propag:1,html_admon:1,readi:1,itself:1,rid:1,minim:1,shorter:1,archiv:1,myslid:1,esubex:1,alert:1,user:1,cwiki:1,recent:1,lower:1,task:1,entri:1,elev:1,propos:1,explan:1,langtangen:1,restructuredtext:[0,1],shortcut:1,informat:1,theorem:[0,1],input:1,subroutin:1,format:[0,1],big:1,bib:1,backquot:1,table2:1,table3:1,semi:1,brace:1,xxdiff:1,resolv:1,"_part0002_mydoc":1,popular:1,ignorn:1,encount:1,sketch:1,often:1,simplifi:1,creation:1,some:1,back:1,understood:1,scale:1,montag:1,per:1,substitut:1,mathemat:[0,1],larg:1,retro:1,prog:1,object:1,run:1,zzz:1,newcommand_replac:1,step:[0,1],qthelp:1,idx:1,materi:1,idl:1,incompress:1,langtangen_2003a:1,block:[0,1],file3:1,file2:1,file1:1,doubl:1,emphasi:1,file4:1,within:1,ensur:1,perl:1,occupi:1,inclus:1,mkd:1,span:1,question:1,nosidebar:1,textual:1,custom:1,guess_encod:1,subst:1,includ:1,suit:1,myfunc:1,properli:1,link:1,translat:1,newer:1,delta:1,line:[0,1],listtyp:1,concaten:1,latex_preambl:1,utf:1,consist:1,inline_tag:1,apricot:1,access:1,someus:1,"export":1,similar:1,knob_left:1,repres:1,incomplet:1,home:1,curl:1,titl:1,invalid:1,bibfil:1,bracket:1,prev1:1,newcommands_keep:1,nice:1,mathpazo:1,colored_table_row:1,svn:1,rst2latex:1,bsummari:1,depth:1,far:1,code:[0,1],partial:1,totem:1,rtf:1,makeidx:1,refs3:1,refs2:1,refs1:1,compact:1,cython:1,showthread:1,elsewher:1,send:1,becam:1,sens:1,fenics_minim:1,docoment:1,titlepag:1,makotempl:1,volum:1,untouch:1,relev:1,tri:1,"20435c":1,button:1,ryan:1,"try":1,impli:1,exted:1,fortun:1,natur:1,odt:1,jump:1,video:1,haiku:1,download:1,click:1,index:[0,1],femdeq:1,compar:1,resembl:1,multimedia:1,cell:1,experiment:1,remove_inline_com:1,mathjax:1,tveito:1,deduc:1,whatev:1,vibrat:1,bibitem:1,matplotlib:1,html_fenic:1,bodi:1,let:1,dmovie15:1,ubuntu:[0,1],vertic:1,sinc:1,convert:1,convers:1,larger:1,chang:1,problemat:1,chanc:1,firefox:1,appli:1,colors1:1,apt:1,cloud:1,from:[0,1],tmp_missing_:1,live:1,mydir:1,next:1,websit:1,few:1,postprocess:1,sort:1,slim:1,comparison:1,trail:1,langtangen_pedersen_2002:1,retriev:1,annoi:1,column:1,obvious:1,meet:1,proof:1,control:1,quickstart:1,process:1,sudo:1,blue_section_head:1,tag:[0,1],doconce_install_al:1,tarbal:1,surfac:1,subdirectori:1,instead:1,sin:1,yellowish:1,frac:1,stop:1,mypack:1,earth2moon:1,exemplifi:1,keep_pygments_html_bg:1,colors2:1,essenti:1,light:1,counter:1,correspond:1,element:1,issu:1,epstopdf:1,allow:1,dmint:1,elif:1,movi:[0,1],move:1,comma:1,libav:1,myprog:1,outer:1,latex_head:1,chosen:1,therefor:1,docx:1,crash:1,python:1,handi:1,dat:1,mention:1,textopc:1,somewher:1,inline_tag_end:1,edit:1,wdiff:1,slide:[0,1],mode:1,mystyl:1,"10pt":1,pygment:1,subset:1,intellig:1,meta:1,subsec:1,our:1,special:[0,1],out:1,variabl:[0,1],matrix:1,esummari:1,sandbox:1,texliv:1,suitabl:1,rel:1,ref:1,red:1,statist:1,insid:1,manipul:1,standalon:1,dictionari:1,pedersen:1,indent:1,could:1,ask:1,movie15:1,keep:1,length:1,outsid:1,navier:1,geometri:1,cyberspac:1,softwar:1,manuscript:1,blogger:1,rbrack:1,texshop:1,date:1,"long":1,mkdir:1,system:1,messag:1,termin:1,siam:1,"final":1,shell:1,bhint:1,bblock:1,cyb:1,rst:1,newtheorem:1,exactli:1,myfram:1,structur:1,charact:1,steer:1,viewer:1,explicit:1,have:1,tabl:[0,1],need:1,turn:1,border:1,table4:1,minted_python:1,preced:1,which:1,divers:1,singl:1,unless:1,preliminari:1,who:1,ooxml:1,awl:1,mplayer:1,twitter_bootstrap:1,segment:1,"class":1,epub:1,"_build":1,todonot:1,latin1:1,url:1,hardcod:1,face:1,pipe:1,bibtex:1,determin:1,ubuntu_vers:1,superscript:1,fact:1,smpeg:1,text:[0,1],skip_inline_com:1,knob_forward:1,blognam:1,graybox1:1,graybox2:1,graybox3:1,thicker:1,emac:[0,1],titlesec:1,html_templat:1,dispers:1,jal:1,"_mydoc":1,suppos:1,conclus:1,local:1,ksh:1,meant:1,mythem:1,contribut:1,familiar:1,autom:1,pressbook:1,enabl:1,bisect:1,theorem_fundamental1:1,ewarn:1,grai:1,blogspot:1,integr:1,contain:1,typset:1,end1:1,frame:1,"_doconce_debug":1,incoveni:1,pngmath:1,correctli:1,boundari:1,written:1,hyperbaseurl:1,neither:1,email:1,kei:1,job:1,entir:1,exclam:1,embed:1,addit:1,hyperref:1,nabla:1,equal:1,thereaft:1,etc:1,eta:1,html_slide_them:1,html5:[0,1],comment:[0,1],cxx:1,guidelin:1,distinguish:1,respect:1,ifthen:1,x_y:1,quit:1,mjpegtool:1,blueish2:1,m2html:1,json:1,treat:1,curli:1,both:1,split_:1,bremark:1,media9:1,togeth:1,graphicx:1,present:1,multi:1,vimeo:1,align:1,defin:[0,1],customiz:1,almost:1,demo:[0,1],texttt:1,site:1,change_encod:1,simulate_and_plot:1,revis:1,scienc:1,satisfi:1,cross:[0,1],handl:1,html_pyramid:1,template_vagr:1,mydoc:1,inc:1,difficult:1,http:1,ref1:1,expans:1,ref3:1,ref2:1,ref5:1,effect:1,a4pap:1,redcloud:1,logfil:1,php:1,expand:1,off:1,center:1,openofficeword:1,nevertheless:1,well:1,difflib:1,autoplai:1,exampl:[0,1],command:1,english:1,undefin:1,usual:1,distanc:1,less:1,obtain:1,tcl:1,fenic:1,web:1,makefil:[0,1],add:1,other:[0,1],bibliographi:[0,1],match:1,dextra_sect:1,css3:1,rememb:1,hpl:1,piec:[0,1],realiz:1,know:1,tick:1,testm:1,insert:1,resid:1,like:1,success:1,unord:1,necessari:1,dlatex_head:1,page:[0,1],"11px":1,underscror:1,captur:1,suppli:1,python_anst:1,scipy_lectur:1,latex_print:1,proper:1,guarante:1,tmp:1,lead:1,avoid:1,yellowbox:1,leav:1,newfil:1,speak:1,mathmpl:1,investig:1,journal:1,usag:1,host:1,encourav:1,although:1,simpler:1,about:1,actual:1,rst2:1,linenumb:1,powerpoint:1,own:1,amsmath:1,automat:1,bsol:1,merg:1,citat:1,pictur:1,trigger:1,"var":1,"function":[0,1],multigrid:1,unexpect:1,ean:1,overflow:1,inlin:[0,1],bug:1,count:1,made:1,wise:1,wish:1,googlecod:1,displai:1,troubl:1,below:1,limit:1,otherwis:1,problem:[0,1],"int":1,dure:1,tmp_preprocess__filenam:1,enotic:1,novemb:1,implement:1,pip:1,sphinxjp:1,probabl:1,detail:1,book:1,bool:1,table_x:1,branch:1,varieti:1,fontspec:1,repeat:1,shown:1,no_mako:1,debian:[0,1],sphinx:[0,1],eof:1,scientif:1,rule:1,portion:1,openoffic:1,f77:1},objtypes:{},titles:["Doconce
Manual","Doconce
Description"],objnames:{},filenames:["index","manual"]})
=======================================
--- /doc/demos/manual/index.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/index.html Fri Jun 28 09:22:02 2013
@@ -41,7 +41,6 @@
<a href="manual.cwiki">Creole wiki</a>,
<a href="manual.mwiki">MediaWiki</a>,
<a href="manual.md">Markdown</a> (Pandoc extended version),
-<a href="manual.st">Structured Text</a>,
<a href="manual.epytext">Epytext</a>,
and maybe the most important format of all:
<a href="manual.txt">plain untagged ASCII text</a>.
=======================================
--- /doc/demos/manual/manual.cwiki Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.cwiki Fri Jun 28 09:22:02 2013
@@ -1,7 +1,7 @@
#summary Doconce Description
<wiki:toc max_depth="2" />
By **Hans Petter Langtangen**
-=== May 29, 2013 ===
+=== Jun 28, 2013 ===
<wiki:comment> lines beginning with # are doconce comment lines
</wiki:comment>
<wiki:comment> (documents can also have mako comment lines) </wiki:comment>
@@ -519,7 +519,7 @@
Transformation of a Doconce document {{{mydoc.do.txt}}} to various other
-formats applies the script {{{doconce format}}}:
+formats apply the script {{{doconce format}}}:
{{{
Terminal> doconce format format mydoc.do.txt
}}}
@@ -1988,7 +1988,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with {{{===}}} heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in {{{html}}} output such that search engines can make use of the them.
== Bibliography ==
@@ -2154,6 +2158,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes {{{|}}} can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+{{{
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+}}}
+
Note that not all formats offer alignment of heading or entries
in tables ({{{rst}}} and {{{sphinx}}} are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2165,6 +2182,33 @@
makes Doconce dump each table to CSV format in a file {{{table_X.csv}}},
where {{{X}}} is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+
+Data in CSV format can be transformed to Doconce table format
+by the {{{doconce csv2table}}} utility:
+
+{{{
+Terminal> doconce csv2table somefile.csv > table.do.txt
+}}}
+This is a quick way of writing tables. For example, we can
+write a text file {{{tmp.csv}}} with
+
+{{{
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+}}}
+Running {{{doconce csv2table tmp.csv}}} creates the table
+
+{{{
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+}}}
== Exercises, Problems, Projects, and Examples ==
@@ -2566,14 +2610,6 @@
\end{align}
!et
}}}
-Here is the result:
-
-{{{
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. label{myeq2}
-\end{align}
-}}}
The support of LaTeX mathematics varies among the formats:
@@ -2651,58 +2687,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-//Example.// Suppose we have the following commands in
-{{{newcommand_replace.tex}}}:
-
-{{{
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-}}}
-
-and these in {{{newcommands_keep.tex}}}:
-
-{{{
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-}}}
-
-The LaTeX block
-{{{
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-}}}
-will then be rendered to
-{{{
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
-\end{eqnarray}
-}}}
-in the current format.
== Admonitions ==
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-{{{block}}}, {{{warning}}}, {{{notice}}}, {{{hint}}}, {{{question}}}, and
{{{summary}}}.
-The box is defined by begin and end tags such as {{{!bhint}}} and
{{{!ehint}}}.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading //Hint// (with number)
-appears, while outside exercises the {{{hint}}} environment gives a
-box with some admonition icon, text and/or colored background.)
+{{{block}}}, {{{warning}}}, {{{notice}}}, {{{question}}}, and
{{{summary}}}.
+The box is defined by begin and end tags such as {{{!bnotice}}} and
{{{!enotice}}}.
The title of the box is fully customizable.
Here are a few examples:
@@ -2712,9 +2709,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -2997,6 +2994,7 @@
== Emacs Doconce Formatter ==
+
The file
[[https://doconce.googlecode.com/hg/misc/.doconce-mode.el|.doconce-mode.el]]
in the Doconce source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3076,7 +3074,9 @@
<wiki:comment> doconce-adjusted styles: easy to switch between styles
since </wiki:comment>
<wiki:comment> font sizes are compatible </wiki:comment>
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
{{{
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3091,6 +3091,16 @@
== LaTeX Beamer Slides ==
+Not yet written...
+
+=== Themes ===
+
+Four themes come with Doconce: {{{X_Y}}}, where {{{X}}} is {{{blue}}} or
{{{red}}}
+(the main color of the slides) and {{{Y}}} is
[[http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf|
{{{plain}}}]]
+for simple layout and
+[[http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf|
{{{shadow}}}]]
+for shadowed boxes and more visual structure in the slides.
+
= Mako Programming =
The [[http://docs.makotemplates.org/|Mako]] templating engine is used
@@ -3100,6 +3110,14 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+//Warning.//
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like {{{${var}}}} to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., {{{${\cal O}(\Delta x^2)$}}} which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+
== The Basics of Mako ==
Just a preliminary sketch of some Mako code (next example is better!):
@@ -3275,6 +3293,15 @@
== General Problems ==
+=== Spellcheck reports a lot of mistakes related LaTeX math ===
+
+The {{{doconce spellcheck}}} command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant {{{tmp_missing_*}}} file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
=== Doconce aborts because of a syntax error that is not an error ===
Doconce searches for typical syntax errors and usually aborts the
@@ -3299,6 +3326,26 @@
* Strings with {{{'T<%.1f'}}} look as openings of Mako blocks ({{{<%}}});
change to {{{'T < %.1f'}}} to avoid this confusion.
+=== The Mako preprocessor claims a variable is undefined ===
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, {{{{\cal O}(\Delta x^2)}}} is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use {{{${}}} anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is {{{${}^+$}}} type of indication of superscripts.
+A suggested rewrite is {{{$\,{}^+$}}}.
+
+The error message will ask you to rerun {{{doconce}}} with
+{{{--mako_strict_undefined}}}, which will display the variable that
+is confusing Mako. However, do not continue to use
+{{{--mako_strict_undefined}}} while you are debugging because this
+variable will then always be undefined in that mode.
+Use {{{# #ifdef}}} directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without {{{--mako_strict_undefined}}}).
+
=== Something goes wrong in the preprocessing step ===
You can examine {{{tmp_preprocess__filename}}} and
{{{tmp_mako__filename}}},
@@ -3670,6 +3717,14 @@
further.
== Problems with HTML Output ==
+
+=== MathJax formulas are not properly rendered ===
+
+Here are some common problems:
+
+
+ * Two equations cannot have identical label (this error often arises
from copying and pasting equations)
+ * {{{[}}} and {{{]}}} brackets must sometimes be replaced by
{{{\lbrack}}} and {{{\rbrack}}}
=== How can I change the layout of the HTML page? ===
=======================================
--- /doc/demos/manual/manual.do.txt Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.do.txt Fri Jun 28 09:22:02 2013
@@ -755,7 +755,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with `===` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in `html` output such that search engines can make use of the them.
===== Bibliography =====
@@ -924,6 +928,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes `|` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+!bc
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+!ec
+
Note that not all formats offer alignment of heading or entries
in tables (`rst` and `sphinx` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -936,6 +953,33 @@
where `X` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the `doconce csv2table` utility:
+
+!bc sys
+Terminal> doconce csv2table somefile.csv > table.do.txt
+!ec
+This is a quick way of writing tables. For example, we can
+write a text file `tmp.csv` with
+
+!bc dat
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+!ec
+Running `doconce csv2table tmp.csv` creates the table
+
+!bc
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+!ec
+
===== Exercises, Problems, Projects, and Examples =====
Doconce has special support for four types of "exercises", named
@@ -1312,6 +1356,7 @@
\end{align}
|et
!ec
+# #ifdef EXTRA
Here is the result:
!bt
@@ -1320,6 +1365,7 @@
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. label{myeq2}
\end{align}
!et
+# #endif
The support of LaTeX mathematics varies among the formats:
@@ -1412,6 +1458,7 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
+# #ifdef EXTRA
__Example.__ Suppose we have the following commands in
`newcommand_replace.tex`:
@@ -1436,23 +1483,20 @@
\eeqa
!et
in the current format.
+# #endif
===== Admonitions =====
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-`block`, `warning`, `notice`, `hint`, `question`, and `summary`.
-The box is defined by begin and end tags such as `!bhint` and `!ehint`.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the `hint` environment gives a
-box with some admonition icon, text and/or colored background.)
+`block`, `warning`, `notice`, `question`, and `summary`.
+The box is defined by begin and end tags such as `!bnotice` and `!enotice`.
The title of the box is fully customizable.
Here are a few examples:
@@ -1462,9 +1506,9 @@
Here is a warning!
|ewarning
-|bhint
+|bnotice Hint
This is a hint.
-|ehint
+|enotice
|bblock This is a block.
A block has never any icon.
@@ -1488,9 +1532,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -1766,6 +1810,10 @@
===== Emacs Doconce Formatter =====
label{emacs:doconce}
+
+## Note: check http://www.latex-community.org/viewtopic.php?f=28&t=208
+## for highly configurable latex editors that perhaps can be adapted
+## to doconce (Kile seems to be the choice because of extensibility)
The
file ".doconce-mode.el": "https://doconce.googlecode.com/hg/misc/.doconce-mode.el"
in the Doconce source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -1854,7 +1902,9 @@
# doconce-adjusted styles: easy to switch between styles since
# font sizes are compatible
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
!bc sys
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -1871,6 +1921,17 @@
===== LaTeX Beamer Slides =====
+Not yet written...
+
+=== Themes ===
+
+Four themes come with Doconce: `X_Y`, where `X` is `blue` or `red`
+(the main color of the slides) and `Y` is "`plain`":
+"http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf"
+for simple layout and
+"`shadow`": "http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf"
+for shadowed boxes and more visual structure in the slides.
+
======= Mako Programming =======
The "Mako": "http://docs.makotemplates.org/" templating engine is used
@@ -1880,6 +1941,15 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+!bwarning
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like `${var}` to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., `${\cal O}(\Delta x^2)$` which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+!ewarning
+
===== The Basics of Mako =====
Just a preliminary sketch of some Mako code (next example is better!):
@@ -2055,6 +2125,15 @@
===== General Problems =====
+=== Spellcheck reports a lot of mistakes related LaTeX math ===
+
+The `doconce spellcheck` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant `tmp_missing_*` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
=== Doconce aborts because of a syntax error that is not an error ===
Doconce searches for typical syntax errors and usually aborts the
@@ -2079,6 +2158,26 @@
* Strings with `'T<%.1f'` look as openings of Mako blocks (`<%`); change
to `'T < %.1f'` to avoid this confusion.
+=== The Mako preprocessor claims a variable is undefined ===
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, ${\cal O}(\Delta x^2)$ is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use `${` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is `${}^+$` type of indication of superscripts.
+A suggested rewrite is `$\,{}^+$`.
+
+The error message will ask you to rerun `doconce` with
+`--mako_strict_undefined`, which will display the variable that
+is confusing Mako. However, do not continue to use
+`--mako_strict_undefined` while you are debugging because this
+variable will then always be undefined in that mode.
+Use `# #ifdef` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without `--mako_strict_undefined`).
+
=== Something goes wrong in the preprocessing step ===
You can examine `tmp_preprocess__filename` and `tmp_mako__filename`,
@@ -2464,6 +2563,14 @@
===== Problems with HTML Output =====
+=== MathJax formulas are not properly rendered ===
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+ * `[` and `]` brackets must sometimes be replaced by `\lbrack` and
`\rbrack`
+
=== How can I change the layout of the HTML page? ===
The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /doc/demos/manual/manual.epytext Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.epytext Fri Jun 28 09:22:02 2013
@@ -1,6 +1,6 @@
TITLE: Doconce Description
BY: Hans Petter Langtangen (Center for Biomedical Computing, Simula
Research Laboratory, and Department of Informatics, University of Oslo)
-DATE: May 29, 2013
+DATE: Jun 28, 2013
What Is Doconce?
================
@@ -548,7 +548,7 @@
=============================
Transformation of a Doconce document C{mydoc.do.txt} to various other
-formats applies the script C{doconce format}::
+formats apply the script C{doconce format}::
Terminal> doconce format format mydoc.do.txt
@@ -2120,7 +2120,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with C{===} heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in C{html} output such that search engines can make use of the them.
Bibliography
------------
@@ -2297,6 +2301,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes C{|} can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like::
+
+
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+
+
Note that not all formats offer alignment of heading or entries
in tables (C{rst} and C{sphinx} are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2309,6 +2326,33 @@
where C{X} is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the C{doconce csv2table} utility::
+
+
+ Terminal> doconce csv2table somefile.csv > table.do.txt
+
+This is a quick way of writing tables. For example, we can
+write a text file C{tmp.csv} with::
+
+
+ time, velocity, acceleration
+ 0.0, 1.4186, -5.01
+ 2.0, 1.376512, 11.919
+ 4.0, 1.1E+1, 14.717624
+
+Running C{doconce csv2table tmp.csv} creates the table::
+
+
+ |------c--------------c--------------c-------|
+ | time | velocity | acceleration |
+ |------c--------------c--------------c-------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------------------|
+
+
Exercises, Problems, Projects, and Examples
-------------------------------------------
@@ -2710,13 +2754,6 @@
it causes problems for Epytext.
-Here is the result::
-
-
- NOTE: A verbatim block has been removed because
- it causes problems for Epytext.
-
-
The support of LaTeX mathematics varies among the formats:
@@ -2809,59 +2846,20 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-I{Example.} Suppose we have the following commands in
-C{newcommand_replace.tex}::
-
-
-
- NOTE: A verbatim block has been removed because
- it causes problems for Epytext.
-
-
-
-and these in C{newcommands_keep.tex}::
-
-
-
- NOTE: A verbatim block has been removed because
- it causes problems for Epytext.
-
-
-
-The LaTeX block::
-
-
-
- NOTE: A verbatim block has been removed because
- it causes problems for Epytext.
-
-
-will then be rendered to::
-
-
- NOTE: A verbatim block has been removed because
- it causes problems for Epytext.
-
-
-in the current format.
Admonitions
-----------
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-C{block}, C{warning}, C{notice}, C{hint}, C{question}, and C{summary}.
-The box is defined by begin and end tags such as C{!bhint} and C{!ehint}.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading I{Hint} (with number)
-appears, while outside exercises the C{hint} environment gives a
-box with some admonition icon, text and/or colored background.)
+C{block}, C{warning}, C{notice}, C{question}, and C{summary}.
+The box is defined by begin and end tags such as C{!bnotice} and
C{!enotice}.
The title of the box is fully customizable.
Here are a few examples::
@@ -2871,9 +2869,9 @@
Here is a warning!
!ewarning
- !bhint
+ !bnotice Hint
This is a hint.
- !ehint
+ !enotice
!bblock This is a block.
A block has never any icon.
@@ -3257,7 +3255,9 @@
------------
-Text is missing... Just a very preliminary sketch of commands::
+Not yet written...
+
+Just a very preliminary sketch of commands::
Terminal> doconce format html myslides \
@@ -3277,6 +3277,17 @@
LaTeX Beamer Slides
-------------------
+Not yet written...
+
+Themes
+~~~~~~
+
+Four themes come with Doconce: C{X_Y}, where C{X} is C{blue} or C{red}
+(the main color of the slides) and C{Y} is
U{C{plain}<http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf>}
+for simple layout and
+U{C{shadow}<http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf>}
+for shadowed boxes and more visual structure in the slides.
+
Mako Programming
================
@@ -3287,6 +3298,14 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+I{Warning.}
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like C{${var}} to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., C{${\cal O}(\Delta x^2)$} which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+
The Basics of Mako
------------------
@@ -3450,6 +3469,16 @@
General Problems
----------------
+Spellcheck reports a lot of mistakes related LaTeX math
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The C{doconce spellcheck} command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant C{tmp_missing_*} file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
Doconce aborts because of a syntax error that is not an error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3477,6 +3506,27 @@
- Strings with C{'T<%.1f'} look as openings of Mako blocks (C{<%}); change
to C{'T < %.1f'} to avoid this confusion.
+The Mako preprocessor claims a variable is undefined
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, M{{\cal O}(\Delta x^2)} is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use C{${} anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is C{${}^+$} type of indication of superscripts.
+A suggested rewrite is C{$\,{}^+$}.
+
+The error message will ask you to rerun C{doconce} with
+C{--mako_strict_undefined}, which will display the variable that
+is confusing Mako. However, do not continue to use
+C{--mako_strict_undefined} while you are debugging because this
+variable will then always be undefined in that mode.
+Use C{# #ifdef} directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without C{--mako_strict_undefined}).
+
Something goes wrong in the preprocessing step
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3912,6 +3962,15 @@
Problems with HTML Output
-------------------------
+
+MathJax formulas are not properly rendered
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some common problems:
+
+ - Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+ - C{[} and C{]} brackets must sometimes be replaced by C{\lbrack} and
C{\rbrack}
How can I change the layout of the HTML page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================
--- /doc/demos/manual/manual.gwiki Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.gwiki Fri Jun 28 09:22:02 2013
@@ -1,7 +1,7 @@
#summary Doconce Description
By *Hans Petter Langtangen*
-==== May 29, 2013 ====
+==== Jun 28, 2013 ====
<wiki:comment> lines beginning with # are doconce comment lines
</wiki:comment>
<wiki:comment> (documents can also have mako comment lines) </wiki:comment>
@@ -518,7 +518,7 @@
Transformation of a Doconce document `mydoc.do.txt` to various other
-formats applies the script `doconce format`:
+formats apply the script `doconce format`:
{{{
Terminal> doconce format format mydoc.do.txt
}}}
@@ -2007,7 +2007,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with `===` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in `html` output such that search engines can make use of the them.
==== Bibliography ====
@@ -2173,6 +2177,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes `|` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+{{{
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+}}}
+
Note that not all formats offer alignment of heading or entries
in tables (`rst` and `sphinx` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2184,6 +2201,33 @@
makes Doconce dump each table to CSV format in a file `table_X.csv`,
where `X` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+
+Data in CSV format can be transformed to Doconce table format
+by the `doconce csv2table` utility:
+
+{{{
+Terminal> doconce csv2table somefile.csv > table.do.txt
+}}}
+This is a quick way of writing tables. For example, we can
+write a text file `tmp.csv` with
+
+{{{
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+}}}
+Running `doconce csv2table tmp.csv` creates the table
+
+{{{
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+}}}
==== Exercises, Problems, Projects, and Examples ====
@@ -2583,14 +2627,6 @@
\end{align}
!et
}}}
-Here is the result:
-
-{{{
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. label{myeq2}
-\end{align}
-}}}
The support of LaTeX mathematics varies among the formats:
@@ -2667,58 +2703,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-*Example.* Suppose we have the following commands in
-`newcommand_replace.tex`:
-
-{{{
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-}}}
-
-and these in `newcommands_keep.tex`:
-
-{{{
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-}}}
-
-The LaTeX block
-{{{
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-}}}
-will then be rendered to
-{{{
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
-\end{eqnarray}
-}}}
-in the current format.
==== Admonitions ====
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-`block`, `warning`, `notice`, `hint`, `question`, and `summary`.
-The box is defined by begin and end tags such as `!bhint` and `!ehint`.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the `hint` environment gives a
-box with some admonition icon, text and/or colored background.)
+`block`, `warning`, `notice`, `question`, and `summary`.
+The box is defined by begin and end tags such as `!bnotice` and `!enotice`.
The title of the box is fully customizable.
Here are a few examples:
@@ -2728,9 +2725,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3091,7 +3088,9 @@
<wiki:comment> doconce-adjusted styles: easy to switch between styles
since </wiki:comment>
<wiki:comment> font sizes are compatible </wiki:comment>
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
{{{
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3106,6 +3105,16 @@
==== LaTeX Beamer Slides ====
+Not yet written...
+
+==== Themes ====
+
+Four themes come with Doconce: `X_Y`, where `X` is `blue` or `red`
+(the main color of the slides) and `Y` is
[http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf `plain`]
+for simple layout and
+[http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf
`shadow`]
+for shadowed boxes and more visual structure in the slides.
+
== Mako Programming ==
The [http://docs.makotemplates.org/ Mako] templating engine is used
@@ -3115,6 +3124,14 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+*Warning.*
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like `${var}` to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., `${\cal O}(\Delta x^2)$` which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+
==== The Basics of Mako ====
Just a preliminary sketch of some Mako code (next example is better!):
@@ -3289,6 +3306,15 @@
==== General Problems ====
+==== Spellcheck reports a lot of mistakes related LaTeX math ====
+
+The `doconce spellcheck` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant `tmp_missing_*` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
==== Doconce aborts because of a syntax error that is not an error ====
Doconce searches for typical syntax errors and usually aborts the
@@ -3313,6 +3339,26 @@
* Strings with `'T<%.1f'` look as openings of Mako blocks (`<%`);
change to `'T < %.1f'` to avoid this confusion.
+==== The Mako preprocessor claims a variable is undefined ====
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, `{\cal O}(\Delta x^2)` is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use `${` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is `${}^+$` type of indication of superscripts.
+A suggested rewrite is `$\,{}^+$`.
+
+The error message will ask you to rerun `doconce` with
+`--mako_strict_undefined`, which will display the variable that
+is confusing Mako. However, do not continue to use
+`--mako_strict_undefined` while you are debugging because this
+variable will then always be undefined in that mode.
+Use `# #ifdef` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without `--mako_strict_undefined`).
+
==== Something goes wrong in the preprocessing step ====
You can examine `tmp_preprocess__filename` and `tmp_mako__filename`,
@@ -3685,6 +3731,14 @@
==== Problems with HTML Output ====
+==== MathJax formulas are not properly rendered ====
+
+Here are some common problems:
+
+
+ * Two equations cannot have identical label (this error often arises
from copying and pasting equations)
+ * `[` and `]` brackets must sometimes be replaced by `\lbrack` and
`\rbrack`
+
==== How can I change the layout of the HTML page? ====
The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /doc/demos/manual/manual.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.html Fri Jun 28 09:22:02 2013
@@ -42,7 +42,7 @@
-webkit-border-radius: 4px; -moz-border-radius: 4px;
border-radius: 4px
color: #555;
- background-color: whiteSmoke;
+ background-color: #f8f8f8;
background-position: 10px 5px;
background-repeat: no-repeat;
background-size: 38px;
@@ -56,7 +56,6 @@
.alert-notice { background-image:
url(https://doconce.googlecode.com/hg/bundled/html_images/small_gray_notice.png);
}
.alert-summary {
background-image:url(https://doconce.googlecode.com/hg/bundled/html_images/small_gray_summary.png);
}
.alert-warning { background-image:
url(https://doconce.googlecode.com/hg/bundled/html_images/small_gray_warning.png);
}
- .alert-hint { background-image:
url(https://doconce.googlecode.com/hg/bundled/html_images/small_gray_hint.png);
}
.alert-question
{background-image:url(https://doconce.googlecode.com/hg/bundled/html_images/small_gray_question.png);
}
</style>
@@ -179,148 +178,161 @@
(' HTML5 Slides ', 2, None, '___sec75'),
(' Potential Problems ', 3, None, '___sec76'),
(' LaTeX Beamer Slides ', 2, None, '___sec77'),
- (' Mako Programming ', 1, None, '___sec78'),
- (' The Basics of Mako ', 2, None, '___sec79'),
+ (' Themes ', 3, None, '___sec78'),
+ (' Mako Programming ', 1, None, '___sec79'),
+ (' The Basics of Mako ', 2, None, '___sec80'),
(' Example: Defining a Theorem Environment ',
2,
'manual:theorem:envir',
'manual:theorem:envir'),
- (' Troubleshooting ', 1, None, '___sec81'),
- (' Disclaimer ', 2, None, '___sec82'),
- (' General Problems ', 2, None, '___sec83'),
+ (' Troubleshooting ', 1, None, '___sec82'),
+ (' Disclaimer ', 2, None, '___sec83'),
+ (' General Problems ', 2, None, '___sec84'),
+ (' Spellcheck reports a lot of mistakes related LaTeX math ',
+ 3,
+ None,
+ '___sec85'),
(' Doconce aborts because of a syntax error that is not an
error ',
3,
None,
- '___sec84'),
+ '___sec86'),
(' The Mako preprocessor is seemingly not run ',
3,
None,
- '___sec85'),
+ '___sec87'),
(' The Mako preprocessor is fooled by Doconce text ',
3,
None,
- '___sec86'),
+ '___sec88'),
+ (' The Mako preprocessor claims a variable is undefined ',
+ 3,
+ None,
+ '___sec89'),
(' Something goes wrong in the preprocessing step ',
3,
None,
- '___sec87'),
- (' Figure captions are incomplete ', 3, None, '___sec88'),
- (' Preprocessor directives do not work ', 3,
None, '___sec89'),
- (' Problems with boldface and emphasize ', 3,
None, '___sec90'),
+ '___sec90'),
+ (' Figure captions are incomplete ', 3, None, '___sec91'),
+ (' Preprocessor directives do not work ', 3,
None, '___sec92'),
+ (' Problems with boldface and emphasize ', 3,
None, '___sec93'),
(' Links to local directories do not work ',
3,
None,
- '___sec91'),
- (' Links are not typeset correctly ', 3, None, '___sec92'),
- (' Inline verbatim code is not detected ', 3,
None, '___sec93'),
+ '___sec94'),
+ (' Links are not typeset correctly ', 3, None, '___sec95'),
+ (' Inline verbatim code is not detected ', 3,
None, '___sec96'),
(' Inline verbatim text is not formatted correctly ',
3,
None,
- '___sec94'),
- (' Strange non-English characters ', 3, None, '___sec95'),
- (' Wrong Norwegian charcters ', 3, None, '___sec96'),
+ '___sec97'),
+ (' Strange non-English characters ', 3, None, '___sec98'),
+ (' Wrong Norwegian charcters ', 3, None, '___sec99'),
(' Too short underlining of reST headlines ',
3,
None,
- '___sec97'),
+ '___sec100'),
(' Found !bt but no tex blocks extracted (BUG) ',
3,
None,
- '___sec98'),
+ '___sec101'),
(' Examples are typset with environment delimiters visible ',
3,
None,
- '___sec99'),
+ '___sec102'),
(' Emacs editing does not work properly because of "regexp
overflow" ',
3,
None,
- '___sec100'),
- (' Problems with code or Tex Blocks ', 2, None, '___sec101'),
- (' Code or math block errors in reST ', 3,
None, '___sec102'),
+ '___sec103'),
+ (' Problems with code or Tex Blocks ', 2, None, '___sec104'),
+ (' Code or math block errors in reST ', 3,
None, '___sec105'),
(' Strange errors around code or TeX blocks in reST ',
3,
None,
- '___sec103'),
+ '___sec106'),
(' Something is wrong with a verbatim code block ',
3,
None,
- '___sec104'),
+ '___sec107'),
(' Code/TeX block is not shown in reST format ',
3,
None,
- '___sec105'),
+ '___sec108'),
(' Verbatim code blocks inside lists look ugly ',
3,
None,
- '___sec106'),
+ '___sec109'),
(' LaTeX code blocks inside lists look ugly ',
3,
None,
- '___sec107'),
- (' Problems with reST/Sphinx Output ', 2, None, '___sec108'),
- (' Title level inconsistent ', 3, None, '___sec109'),
- (' Lists do not appear in .rst files ', 3,
None, '___sec110'),
+ '___sec110'),
+ (' Problems with reST/Sphinx Output ', 2, None, '___sec111'),
+ (' Title level inconsistent ', 3, None, '___sec112'),
+ (' Lists do not appear in .rst files ', 3,
None, '___sec113'),
(' Error message "Undefined substitution..." from reST ',
3,
None,
- '___sec111'),
- (' Warning about duplicate link names ', 3,
None, '___sec112'),
- (' Inconsistent headings in reST ', 3, None, '___sec113'),
+ '___sec114'),
+ (' Warning about duplicate link names ', 3,
None, '___sec115'),
+ (' Inconsistent headings in reST ', 3, None, '___sec116'),
(' No code environment appears before "bc ipy" blocks ',
3,
None,
- '___sec114'),
- (' Problems with LaTeX Output ', 2, None, '___sec115'),
+ '___sec117'),
+ (' Problems with LaTeX Output ', 2, None, '___sec118'),
(' LaTeX does not like underscores in URLs ',
3,
None,
- '___sec116'),
+ '___sec119'),
(" Error when running latex: You must have 'pygmentize'
installed ",
3,
None,
- '___sec117'),
+ '___sec120'),
(' Why are the LaTeX section headings smaller than normal? ',
3,
None,
- '___sec118'),
+ '___sec121'),
(' Can I have LaTeX figures with shadows? ',
3,
None,
- '___sec119'),
+ '___sec122'),
(' How can I use my fancy LaTeX environments? ',
3,
None,
- '___sec120'),
- (' The LaTeX file does not compile ', 3, None, '___sec121'),
- (' Inline verbatim gives error ', 3, None, '___sec122'),
- (' Errors in figure captions ', 3, None, '___sec123'),
- (' Chapters are ignored ', 3, None, '___sec124'),
+ '___sec123'),
+ (' The LaTeX file does not compile ', 3, None, '___sec124'),
+ (' Inline verbatim gives error ', 3, None, '___sec125'),
+ (' Errors in figure captions ', 3, None, '___sec126'),
+ (' Chapters are ignored ', 3, None, '___sec127'),
(' I want to tune the top of the LaTeX file ',
3,
None,
- '___sec125'),
- (' Problems with gwiki Output ', 2, None, '___sec126'),
- (' Strange nested lists in gwiki ', 3, None, '___sec127'),
+ '___sec128'),
+ (' Problems with gwiki Output ', 2, None, '___sec129'),
+ (' Strange nested lists in gwiki ', 3, None, '___sec130'),
(' Lists in gwiki look ugly in the gwiki source ',
3,
+ None,
+ '___sec131'),
+ (' Problems with HTML Output ', 2, None, '___sec132'),
+ (' MathJax formulas are not properly rendered ',
+ 3,
None,
- '___sec128'),
- (' Problems with HTML Output ', 2, None, '___sec129'),
+ '___sec133'),
(' How can I change the layout of the HTML page? ',
3,
None,
- '___sec130'),
+ '___sec134'),
(' Why do figures look ugly when using HTML templates? ',
3,
None,
- '___sec131'),
- (' Debugging ', 2, None, '___sec132'),
- (' Basic Parsing Ideas ', 1, None, '___sec133'),
+ '___sec135'),
+ (' Debugging ', 2, None, '___sec136'),
+ (' Basic Parsing Ideas ', 1, None, '___sec137'),
(' Typesetting of Function Arguments, Return Values, and
Variables ',
2,
None,
- '___sec134'),
- (' References ', 1, None, '___sec135')]}
+ '___sec138'),
+ (' References ', 1, None, '___sec139')]}
end of tocinfo -->
<body>
@@ -342,23 +354,10 @@
<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7">
-<!-- newcommands_keep.tex -->
-$$
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-$$
+
-<!-- newcommands_replace.tex -->
-$$
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-$$
+
@@ -385,7 +384,7 @@
<center>[1] <b>Center for Biomedical Computing, Simula Research
Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<p>
-<center><h4>May 29, 2013</h4></center> <!-- date -->
+<center><h4>Jun 28, 2013</h4></center> <!-- date -->
<p>
<!-- lines beginning with # are doconce comment lines -->
<!-- (documents can also have mako comment lines) -->
@@ -1014,7 +1013,7 @@
<p>
Transformation of a Doconce document <code>mydoc.do.txt</code> to various
other
-formats applies the script <code>doconce format</code>:
+formats apply the script <code>doconce format</code>:
<!-- begin verbatim block sys-->
<pre><code>Terminal> doconce format format mydoc.do.txt
</code></pre>
@@ -2776,7 +2775,12 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with <code>===</code> heading,
+the index keywords should be placed above the heading.
+
+<p>
+The keywords in the index are automatically placed in a meta
+tag in <code>html</code> output such that search engines can make use of
the them.
<h3>Bibliography <a name="___sec53"></a></h3>
@@ -2969,6 +2973,22 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes <code>|</code> can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+<p>
+<!-- begin verbatim block -->
+<pre><code> |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+</code></pre>
+<!-- end verbatim block -->
+
+<p>
Note that not all formats offer alignment of heading or entries
in tables (<code>rst</code> and <code>sphinx</code> are examples). Also
note that
Doconce tables are very simple: neither entries nor
@@ -2982,6 +3002,40 @@
where <code>X</code> is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+<p>
+Data in CSV format can be transformed to Doconce table format
+by the <code>doconce csv2table</code> utility:
+
+<p>
+<!-- begin verbatim block sys-->
+<pre><code>Terminal> doconce csv2table somefile.csv > table.do.txt
+</code></pre>
+<!-- end verbatim block -->
+This is a quick way of writing tables. For example, we can
+write a text file <code>tmp.csv</code> with
+
+<p>
+<!-- begin verbatim block dat-->
+<pre><code>time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+</code></pre>
+<!-- end verbatim block -->
+Running <code>doconce csv2table tmp.csv</code> creates the table
+
+<p>
+<!-- begin verbatim block -->
+<pre><code>|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+</code></pre>
+<!-- end verbatim block -->
+
<h3>Exercises, Problems, Projects, and Examples <a
name="___sec62"></a></h3>
<p>
@@ -3418,16 +3472,6 @@
!et
</code></pre>
<!-- end verbatim block -->
-Here is the result:
-
-<p>
-$$
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, \label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. \label{myeq2}
-\end{align}
-$$
-
<p>
The support of LaTeX mathematics varies among the formats:
@@ -3532,57 +3576,11 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-<p>
-<b>Example.</b>
-Suppose we have the following commands in
-<code>newcommand_replace.tex</code>:
-
-<p>
-<!-- begin verbatim block latexpro-->
-<pre><code>\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-</code></pre>
-<!-- end verbatim block -->
-
-<p>
-and these in <code>newcommands_keep.tex</code>:
-
-<p>
-<!-- begin verbatim block latexpro-->
-<pre><code>\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-</code></pre>
-<!-- end verbatim block -->
-
-<p>
-The LaTeX block
-<!-- begin verbatim block -->
-<pre><code>\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-</code></pre>
-<!-- end verbatim block -->
-will then be rendered to
-$$
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, \label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } \label{my:eq2}
-\end{eqnarray}
-$$
-
-in the current format.
-
<h3>Admonitions <a name="___sec67"></a></h3>
<p>
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
@@ -3590,12 +3588,8 @@
<p>
The following admonition environments are available:
-<code>block</code>, <code>warning</code>, <code>notice</code>,
<code>hint</code>, <code>question</code>, and <code>summary</code>.
-The box is defined by begin and end tags such as <code>!bhint</code> and
<code>!ehint</code>.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading <em>Hint</em> (with number)
-appears, while outside exercises the <code>hint</code> environment gives a
-box with some admonition icon, text and/or colored background.)
+<code>block</code>, <code>warning</code>, <code>notice</code>,
<code>question</code>, and <code>summary</code>.
+The box is defined by begin and end tags such as <code>!bnotice</code> and
<code>!enotice</code>.
The title of the box is fully customizable.
<p>
@@ -3607,9 +3601,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3635,7 +3629,7 @@
Here is a warning!
</div>
<p>
-<div class="alert alert-block alert-hint alert-text-normal"><b>Hint.</b>
+<div class="alert alert-block alert-notice alert-text-normal"><b>Hint.</b>
This is a hint.
</div>
<p>
@@ -4041,8 +4035,11 @@
<!-- doconce-adjusted styles: easy to switch between styles since -->
<!-- font sizes are compatible -->
+<p>
+Not yet written...
+
<p>
-Text is missing... Just a very preliminary sketch of commands:
+Just a very preliminary sketch of commands:
<!-- begin verbatim block sys-->
<pre><code>Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -4064,7 +4061,19 @@
<h3>LaTeX Beamer Slides <a name="___sec77"></a></h3>
-<h2>Mako Programming <a name="___sec78"></a></h2>
+<p>
+Not yet written...
+
+<h4>Themes <a name="___sec78"></a></h4>
+
+<p>
+Four themes come with Doconce: <code>X_Y</code>, where <code>X</code> is
<code>blue</code> or <code>red</code>
+(the main color of the slides) and <code>Y</code> is <a
href="http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf"><tt>plain</tt></a>
+for simple layout and
+<a
href="http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf"><tt>shadow</tt></a>
+for shadowed boxes and more visual structure in the slides.
+
+<h2>Mako Programming <a name="___sec79"></a></h2>
<p>
The <a href="http://docs.makotemplates.org/">Mako</a> templating engine is
used
@@ -4074,7 +4083,16 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
-<h3>The Basics of Mako <a name="___sec79"></a></h3>
+<p>
+<div class="alert alert-block alert-warning
alert-text-normal"><b>Warning.</b>
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like <code>${var}</code> to
extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., <code>${\cal O}(\Delta x^2)$</code> which looks
like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+</div>
+<h3>The Basics of Mako <a name="___sec80"></a></h3>
<p>
Just a preliminary sketch of some Mako code (next example is better!):
@@ -4243,9 +4261,9 @@
the <code>ptex2tex</code> program with all its flexibility for choosing
environments.
Also <code>doconce ptex2tex</code> has some flexibility for typesetting
computer code.
-<h2>Troubleshooting <a name="___sec81"></a></h2>
+<h2>Troubleshooting <a name="___sec82"></a></h2>
-<h3>Disclaimer <a name="___sec82"></a></h3>
+<h3>Disclaimer <a name="___sec83"></a></h3>
<p>
Doconce has some support for syntax checking. If you encounter Python
@@ -4256,9 +4274,19 @@
regular expressions may sometimes fail. Therefore, there is a chance that
legal
Doconce syntax is not treated properly.
-<h3>General Problems <a name="___sec83"></a></h3>
+<h3>General Problems <a name="___sec84"></a></h3>
-<h4>Doconce aborts because of a syntax error that is not an error <a
name="___sec84"></a></h4>
+<h4>Spellcheck reports a lot of mistakes related LaTeX math <a
name="___sec85"></a></h4>
+
+<p>
+The <code>doconce spellcheck</code> command should ignore LaTeX math, but
if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant <code>tmp_missing_*</code> file and search for the math
expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
+<h4>Doconce aborts because of a syntax error that is not an error <a
name="___sec86"></a></h4>
<p>
Doconce searches for typical syntax errors and usually aborts the
@@ -4268,7 +4296,7 @@
<code>--no_abort</code> option on the command line. You may send an email
to the Doconce author at <code>h...@simula.no</code> and report the problem.
-<h4>The Mako preprocessor is seemingly not run <a
name="___sec85"></a></h4>
+<h4>The Mako preprocessor is seemingly not run <a
name="___sec87"></a></h4>
<p>
If you have lines starting with <code>%</code> inside code segments (for
example,
@@ -4277,7 +4305,7 @@
this problem and avoids running Mako. Examine the output from
Doconce: warnings are issued if Mako is not run.
-<h4>The Mako preprocessor is fooled by Doconce text <a
name="___sec86"></a></h4>
+<h4>The Mako preprocessor is fooled by Doconce text <a
name="___sec88"></a></h4>
<p>
Here are possible problems for Mako:
@@ -4289,7 +4317,29 @@
to <code>'T < %.1f'</code> to avoid this confusion.</li>
</ul>
-<h4>Something goes wrong in the preprocessing step <a
name="___sec87"></a></h4>
+<h4>The Mako preprocessor claims a variable is undefined <a
name="___sec89"></a></h4>
+
+<p>
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, \( {\cal O}(\Delta x^2) \) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use <code>${</code> anywhere in LaTeX
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is <code>${}^+$</code> type of indication of
superscripts.
+A suggested rewrite is <code>$\,{}^+$</code>.
+
+<p>
+The error message will ask you to rerun <code>doconce</code> with
+<code>--mako_strict_undefined</code>, which will display the variable that
+is confusing Mako. However, do not continue to use
+<code>--mako_strict_undefined</code> while you are debugging because this
+variable will then always be undefined in that mode.
+Use <code># #ifdef</code> directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without <code>--mako_strict_undefined</code>).
+
+<h4>Something goes wrong in the preprocessing step <a
name="___sec90"></a></h4>
<p>
You can examine <code>tmp_preprocess__filename</code> and
<code>tmp_mako__filename</code>,
@@ -4300,7 +4350,7 @@
of the output from Doconce to see exactly which preprocessors are run
and on which files.
-<h4>Figure captions are incomplete <a name="___sec88"></a></h4>
+<h4>Figure captions are incomplete <a name="___sec91"></a></h4>
<p>
If only the first part of a figure caption in the Doconce file is seen
@@ -4308,20 +4358,20 @@
occupies multiple lines in the Doconce file. The figure caption must
be written as <em>one line</em>, at the same line as the FIGURE keyword.
-<h4>Preprocessor directives do not work <a name="___sec89"></a></h4>
+<h4>Preprocessor directives do not work <a name="___sec92"></a></h4>
<p>
Make sure the preprocessor instructions, in Preprocess or Mako, have
correct syntax. Also make sure that you do not mix Preprocess and Mako
instructions. Doconce will then only run Preprocess.
-<h4>Problems with boldface and emphasize <a name="___sec90"></a></h4>
+<h4>Problems with boldface and emphasize <a name="___sec93"></a></h4>
<p>
Two boldface or emphasize expressions after each other are not rendered
correctly. Merge them into one common expression.
-<h4>Links to local directories do not work <a name="___sec91"></a></h4>
+<h4>Links to local directories do not work <a name="___sec94"></a></h4>
<p>
Links of the type
@@ -4340,7 +4390,7 @@
With plain <code>html</code> output only, you can link to whatever, but
remember
to move all files you link to if you move the primary <code>.html</code>
file.
-<h4>Links are not typeset correctly <a name="___sec92"></a></h4>
+<h4>Links are not typeset correctly <a name="___sec95"></a></h4>
<p>
Not all formats will allow formatting of the links. Verbatim words
@@ -4357,17 +4407,17 @@
The back-ticks must be removed, or the text can be reformulated as
in the line above it.
-<h4>Inline verbatim code is not detected <a name="___sec93"></a></h4>
+<h4>Inline verbatim code is not detected <a name="___sec96"></a></h4>
<p>
Make sure there is a space before the first back-tick.
-<h4>Inline verbatim text is not formatted correctly <a
name="___sec94"></a></h4>
+<h4>Inline verbatim text is not formatted correctly <a
name="___sec97"></a></h4>
<p>
Make sure there is whitespace surrounding the text in back-ticks.
-<h4>Strange non-English characters <a name="___sec95"></a></h4>
+<h4>Strange non-English characters <a name="___sec98"></a></h4>
<p>
The former reason for this problem is that Doconce could only work with
latin1
@@ -4389,7 +4439,7 @@
</code></pre>
<!-- end verbatim block -->
-<h4>Wrong Norwegian charcters <a name="___sec96"></a></h4>
+<h4>Wrong Norwegian charcters <a name="___sec99"></a></h4>
<p>
When Doconce documents have characters not in the standard ASCII set,
@@ -4397,20 +4447,20 @@
the section "Strange non-English characters" above for how to
run <code>doconce change_encoding</code> to change the encoding of the
Doconce file.
-<h4>Too short underlining of reST headlines <a name="___sec97"></a></h4>
+<h4>Too short underlining of reST headlines <a name="___sec100"></a></h4>
<p>
This may happen if there is a paragraph heading without
proceeding text before some section heading.
-<h4>Found !bt but no tex blocks extracted (BUG) <a
name="___sec98"></a></h4>
+<h4>Found !bt but no tex blocks extracted (BUG) <a
name="___sec101"></a></h4>
<p>
This message points to a bug, but has been resolved by removing blank lines
between the text and the first <code>!bt</code> (inserting the blanks
again did not
trigger the error message again...).
-<h4>Examples are typset with environment delimiters visible <a
name="___sec99"></a></h4>
+<h4>Examples are typset with environment delimiters visible <a
name="___sec102"></a></h4>
<p>
If you see an Example section containing <code>!bsubex</code>,
<code>!bsol</code>, or other
@@ -4419,7 +4469,7 @@
option <code>--examples_as_exercises</code>. The text in the example is
typeset
as is unless this option is included.
-<h4>Emacs editing does not work properly because of "regexp overflow" <a
name="___sec100"></a></h4>
+<h4>Emacs editing does not work properly because of "regexp overflow" <a
name="___sec103"></a></h4>
<p>
Sometimes the Doonce editing mode (see the section <a
href="#emacs:doconce">Emacs Doconce Formatter</a>) in Emacs
@@ -4430,9 +4480,9 @@
The error message comes with the Doconce file contains too much text
for Emacs to handle.
-<h3>Problems with code or Tex Blocks <a name="___sec101"></a></h3>
+<h3>Problems with code or Tex Blocks <a name="___sec104"></a></h3>
-<h4>Code or math block errors in reST <a name="___sec102"></a></h4>
+<h4>Code or math block errors in reST <a name="___sec105"></a></h4>
<p>
First note that a code or math block must come after some plain
@@ -4454,7 +4504,7 @@
at the preceding line will appear (which is the right way in reST to
indicate a verbatim block of text).
-<h4>Strange errors around code or TeX blocks in reST <a
name="___sec103"></a></h4>
+<h4>Strange errors around code or TeX blocks in reST <a
name="___sec106"></a></h4>
<p>
If <code>idx</code> commands for defining indices are placed inside
paragraphs,
@@ -4464,21 +4514,21 @@
other formats. The remedy is to define items for the index outside
paragraphs.
-<h4>Something is wrong with a verbatim code block <a
name="___sec104"></a></h4>
+<h4>Something is wrong with a verbatim code block <a
name="___sec107"></a></h4>
<p>
Check first that there is a "normal" sentence right before
the block (this is important for reST and similar
"ASCII-close" formats).
-<h4>Code/TeX block is not shown in reST format <a
name="___sec105"></a></h4>
+<h4>Code/TeX block is not shown in reST format <a
name="___sec108"></a></h4>
<p>
A comment right before a code or tex block will treat the whole
block also as a comment. It is important that there is normal
running text right before <code>!bt</code> and <code>!bc</code>
environments.
-<h4>Verbatim code blocks inside lists look ugly <a
name="___sec106"></a></h4>
+<h4>Verbatim code blocks inside lists look ugly <a
name="___sec109"></a></h4>
<p>
Read the the section <a href="#sec:verbatim:blocks">Blocks of Verbatim
Computer Code</a> above. Start the
@@ -4488,7 +4538,7 @@
paragraph headings instead. In fact, that is what is recommended:
avoid verbatim code blocks inside lists (it makes life easier).
-<h4>LaTeX code blocks inside lists look ugly <a name="___sec107"></a></h4>
+<h4>LaTeX code blocks inside lists look ugly <a name="___sec110"></a></h4>
<p>
Same solution as for computer code blocks as described in the
@@ -4496,36 +4546,36 @@
and that the rest of the non-LaTeX surrounding text is correctly indented.
Using paragraphs instead of list items is a good idea also here.
-<h3>Problems with reST/Sphinx Output <a name="___sec108"></a></h3>
+<h3>Problems with reST/Sphinx Output <a name="___sec111"></a></h3>
-<h4>Title level inconsistent <a name="___sec109"></a></h4>
+<h4>Title level inconsistent <a name="___sec112"></a></h4>
<p>
reST does not like jumps in the levels of headings. For example, you cannot
have a <code>===</code> (paragraph) heading after a <code>=======</code>
(section) heading without
a <code>=====</code> (subsection) heading in between.
-<h4>Lists do not appear in .rst files <a name="___sec110"></a></h4>
+<h4>Lists do not appear in .rst files <a name="___sec113"></a></h4>
<p>
Check if you have a comment right above the list. That comment
will include the list if the list is indentend. Remove the comment.
-<h4>Error message "Undefined substitution..." from reST <a
name="___sec111"></a></h4>
+<h4>Error message "Undefined substitution..." from reST <a
name="___sec114"></a></h4>
<p>
This may happen if there is much inline math in the text. reST cannot
understand inline LaTeX commands and interprets them as illegal code.
Just ignore these error messages.
-<h4>Warning about duplicate link names <a name="___sec112"></a></h4>
+<h4>Warning about duplicate link names <a name="___sec115"></a></h4>
<p>
Link names should be unique, but if (e.g.) "file" is used as link text
several places in a reST file, the links still work. The warning can
therefore be ignorned.
-<h4>Inconsistent headings in reST <a name="___sec113"></a></h4>
+<h4>Inconsistent headings in reST <a name="___sec116"></a></h4>
<p>
The <code>rst2*.py</code> and Sphinx converters abort if the headers of
sections
@@ -4535,7 +4585,7 @@
count the number of equality signs (or underscores if you use that)
and make sure they decrease by two every time a lower level is encountered.
-<h4>No code environment appears before "bc ipy" blocks <a
name="___sec114"></a></h4>
+<h4>No code environment appears before "bc ipy" blocks <a
name="___sec117"></a></h4>
<p>
The <code>!bc ipy</code> directive behaves this way for
<code>sphinx</code> output because
@@ -4543,9 +4593,9 @@
appropriate, shift to <code>!bc cod</code> or another specification of the
verbatim environment.
-<h3>Problems with LaTeX Output <a name="___sec115"></a></h3>
+<h3>Problems with LaTeX Output <a name="___sec118"></a></h3>
-<h4>LaTeX does not like underscores in URLs <a name="___sec116"></a></h4>
+<h4>LaTeX does not like underscores in URLs <a name="___sec119"></a></h4>
<p>
Suppose you have a URL reference like
@@ -4568,7 +4618,7 @@
<!-- end verbatim block -->
Verbatim text in links works fine with underscores.
-<h4>Error when running latex: You must have 'pygmentize' installed <a
name="___sec117"></a></h4>
+<h4>Error when running latex: You must have 'pygmentize' installed <a
name="___sec120"></a></h4>
<p>
This message points to the use of the minted style for typesetting verbatim
@@ -4585,7 +4635,7 @@
When this package is included, <code>latex</code> or <code>pdflatex</code>
runs the
<code>pygmentize</code> program and the <code>shell-escape</code> option
is required.
-<h4>Why are the LaTeX section headings smaller than normal? <a
name="___sec118"></a></h4>
+<h4>Why are the LaTeX section headings smaller than normal? <a
name="___sec121"></a></h4>
<p>
Doconce inserts a special command to make the headings
@@ -4611,7 +4661,7 @@
by replacing <code>[compact]</code> by <code>[compact,small]</code> as
parameter specification
for <code>titlesec</code>.
-<h4>Can I have LaTeX figures with shadows? <a name="___sec119"></a></h4>
+<h4>Can I have LaTeX figures with shadows? <a name="___sec122"></a></h4>
<p>
This is easy by including the <code>fancybox</code> and
<code>graphicx</code> packages
@@ -4627,14 +4677,14 @@
</code></pre>
<!-- end verbatim block -->
-<h4>How can I use my fancy LaTeX environments? <a
name="___sec120"></a></h4>
+<h4>How can I use my fancy LaTeX environments? <a
name="___sec123"></a></h4>
<p>
See the section <a href="#manual:theorem:envir">Example: Defining a
Theorem Environment</a> for how to make a custom
theorem environment also in Doconce, without using implementations
restricted to LaTeX.
-<h4>The LaTeX file does not compile <a name="___sec121"></a></h4>
+<h4>The LaTeX file does not compile <a name="___sec124"></a></h4>
<p>
If the problem is undefined control sequence involving
@@ -4646,7 +4696,7 @@
Doconce file) spans more than one line. Make sure, in the Doconce source,
that all inline verbatim text appears on the same line.
-<h4>Inline verbatim gives error <a name="___sec122"></a></h4>
+<h4>Inline verbatim gives error <a name="___sec125"></a></h4>
<p>
Check if the inline verbatim contains typical LaTeX commands, e.g.,
@@ -4666,7 +4716,7 @@
<!-- Could have doconce configure file where inline verbatim is -->
<!-- configured to be \fontsize... directly, not via ptex2tex \code{}. -->
-<h4>Errors in figure captions <a name="___sec123"></a></h4>
+<h4>Errors in figure captions <a name="___sec126"></a></h4>
<p>
Such errors typically arise from unbalanced curly braces, or dollar signs
@@ -4678,14 +4728,14 @@
a proper <code>texttt</code> command (since verbatim font constructions
does not work
inside figure captions) and precede underscores by backslash.)
-<h4>Chapters are ignored <a name="___sec124"></a></h4>
+<h4>Chapters are ignored <a name="___sec127"></a></h4>
<p>
The default LaTeX style is "article". If you chapters in the Doconce file,
you need to run <code>ptex2tex</code> with the option <code>-DBOOK</code>
to set the LaTeX
documentstyle to "book".
-<h4>I want to tune the top of the LaTeX file <a name="___sec125"></a></h4>
+<h4>I want to tune the top of the LaTeX file <a name="___sec128"></a></h4>
<p>
The top of the LaTeX file, as generated by Doconce, is very simple.
@@ -4713,15 +4763,15 @@
replaced by the hand-written LaTeX "top" file.</li>
</ol>
-<h3>Problems with gwiki Output <a name="___sec126"></a></h3>
+<h3>Problems with gwiki Output <a name="___sec129"></a></h3>
-<h4>Strange nested lists in gwiki <a name="___sec127"></a></h4>
+<h4>Strange nested lists in gwiki <a name="___sec130"></a></h4>
<p>
Doconce cannot handle nested lists correctly in the gwiki format.
Use nonnested lists or edit the <code>.gwiki</code> file directly.
-<h4>Lists in gwiki look ugly in the gwiki source <a
name="___sec128"></a></h4>
+<h4>Lists in gwiki look ugly in the gwiki source <a
name="___sec131"></a></h4>
<p>
Because the Google Code wiki format requires all text of a list item to
@@ -4731,9 +4781,22 @@
is seldom to be looked at - it is the Doconce source that one edits
further.
-<h3>Problems with HTML Output <a name="___sec129"></a></h3>
+<h3>Problems with HTML Output <a name="___sec132"></a></h3>
+
+<h4>MathJax formulas are not properly rendered <a
name="___sec133"></a></h4>
+
+<p>
+Here are some common problems:
+
+<p>
+
+<ul>
+ <li> Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)</li>
+ <li> <code>[</code> and <code>]</code> brackets must sometimes be
replaced by <code>\lbrack</code> and <code>\rbrack</code></li>
+</ul>
-<h4>How can I change the layout of the HTML page? <a
name="___sec130"></a></h4>
+<h4>How can I change the layout of the HTML page? <a
name="___sec134"></a></h4>
<p>
The easiest way is to edit the HTML style or the HTML code directly.
@@ -4775,7 +4838,7 @@
The easiest way is to get fancy layouts in HTML is to
use the <code>sphinx</code> format and one its many themes.
-<h4>Why do figures look ugly when using HTML templates? <a
name="___sec131"></a></h4>
+<h4>Why do figures look ugly when using HTML templates? <a
name="___sec135"></a></h4>
<p>
The HTML header that Doconce generates contain special styles for
@@ -4794,7 +4857,7 @@
</code></pre>
<!-- end verbatim block -->
-<h3>Debugging <a name="___sec132"></a></h3>
+<h3>Debugging <a name="___sec136"></a></h3>
<p>
Given a problem, extract a small portion of text surrounding the
@@ -4807,7 +4870,7 @@
Ideas" explains how the Doconce text is transformed into a specific
format, and you need to know these steps to make use of the logfile.
-<h2>Basic Parsing Ideas <a name="___sec133"></a></h2>
+<h2>Basic Parsing Ideas <a name="___sec137"></a></h2>
<p>
<!-- avoid list here since we have code in between (never a good idea) -->
@@ -4860,7 +4923,7 @@
the document to another, more complex format, say reST or
LaTeX, and work further on the document in this format.
-<h3>Typesetting of Function Arguments, Return Values, and Variables <a
name="___sec134"></a></h3>
+<h3>Typesetting of Function Arguments, Return Values, and Variables <a
name="___sec138"></a></h3>
<p>
As part of comments (or doc strings) in computer code one often wishes
@@ -4903,7 +4966,7 @@
the iterations.
</dl>
-<h2>References <a name="___sec135"></a></h2>
+<h2>References <a name="___sec139"></a></h2>
<h2>Bibliography</h2>
=======================================
--- /doc/demos/manual/manual.md Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.md Fri Jun 28 09:22:02 2013
@@ -1,6 +1,6 @@
% Doconce Description
% Hans Petter Langtangen at Center for Biomedical Computing, Simula
Research Laboratory and Department of Informatics, University of Oslo
-% May 29, 2013
+% Jun 28, 2013
<!-- lines beginning with # are doconce comment lines -->
<!-- (documents can also have mako comment lines) -->
@@ -596,7 +596,7 @@
## From Doconce to Other Formats
Transformation of a Doconce document `mydoc.do.txt` to various other
-formats applies the script `doconce format`:
+formats apply the script `doconce format`:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.Bash}
Terminal> doconce format format mydoc.do.txt
@@ -2265,7 +2265,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with `===` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in `html` output such that search engines can make use of the them.
### Bibliography
@@ -2445,6 +2449,20 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes `|` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
Note that not all formats offer alignment of heading or entries
in tables (`rst` and `sphinx` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2457,6 +2475,38 @@
where `X` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the `doconce csv2table` utility:
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.Bash}
+Terminal> doconce csv2table somefile.csv > table.do.txt
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a quick way of writing tables. For example, we can
+write a text file `tmp.csv` with
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.Python}
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Running `doconce csv2table tmp.csv` creates the table
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
### Exercises, Problems, Projects, and Examples
Doconce has special support for four types of "exercises", named
@@ -2881,20 +2931,6 @@
!et
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Here is the result:
-
-$$
-\begin{equation}
-{\partial u\over\partial t} = \nabla^2 u + f, \label{myeq1}
-\end{equation}
-$$
-
-$$
-\begin{equation}
-{\partial v\over\partial t} = \nabla\cdot(q(u)\nabla v) + g. \label{myeq2}
-\end{equation}
-$$
-
The support of LaTeX mathematics varies among the formats:
* Output in LaTeX (`latex` and `pdflatex` formats) has of course full
@@ -2992,62 +3028,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-*Example.* Suppose we have the following commands in
-`newcommand_replace.tex`:
-
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-and these in `newcommands_keep.tex`:
-
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The LaTeX block
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-\beqa
-\x\cdot\normalvec &=& 0, \label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep \label{my:eq2}
-\eeqa
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-will then be rendered to
-$$
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, \label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } \label{my:eq2}
-\end{eqnarray}
-$$
-in the current format.
### Admonitions
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-`block`, `warning`, `notice`, `hint`, `question`, and `summary`.
-The box is defined by begin and end tags such as `!bhint` and `!ehint`.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the `hint` environment gives a
-box with some admonition icon, text and/or colored background.)
+`block`, `warning`, `notice`, `question`, and `summary`.
+The box is defined by begin and end tags such as `!bnotice` and `!enotice`.
The title of the box is fully customizable.
Here are a few examples:
@@ -3058,9 +3051,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3464,7 +3457,9 @@
<!-- doconce-adjusted styles: easy to switch between styles since -->
<!-- font sizes are compatible -->
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.Bash}
Terminal> doconce format html myslides \
@@ -3483,6 +3478,16 @@
### LaTeX Beamer Slides
+Not yet written...
+
+#### Themes
+
+Four themes come with Doconce: `X_Y`, where `X` is `blue` or `red`
+(the main color of the slides) and `Y` is
[`plain`](http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf)
+for simple layout and
+[`shadow`](http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf)
+for shadowed boxes and more visual structure in the slides.
+
## Mako Programming
The [Mako](http://docs.makotemplates.org/) templating engine is used
@@ -3492,6 +3497,14 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+*Warning.*
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like `${var}` to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., `${\cal O}(\Delta x^2)$` which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+
### The Basics of Mako
Just a preliminary sketch of some Mako code (next example is better!):
@@ -3675,6 +3688,15 @@
### General Problems
+#### Spellcheck reports a lot of mistakes related LaTeX math
+
+The `doconce spellcheck` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant `tmp_missing_*` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
#### Doconce aborts because of a syntax error that is not an error
Doconce searches for typical syntax errors and usually aborts the
@@ -3699,6 +3721,26 @@
* Strings with `'T<%.1f'` look as openings of Mako blocks (`<%`); change
to `'T < %.1f'` to avoid this confusion.
+#### The Mako preprocessor claims a variable is undefined
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, ${\cal O}(\Delta x^2)$ is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use `${` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is `${}^+$` type of indication of superscripts.
+A suggested rewrite is `$\,{}^+$`.
+
+The error message will ask you to rerun `doconce` with
+`--mako_strict_undefined`, which will display the variable that
+is confusing Mako. However, do not continue to use
+`--mako_strict_undefined` while you are debugging because this
+variable will then always be undefined in that mode.
+Use `# #ifdef` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without `--mako_strict_undefined`).
+
#### Something goes wrong in the preprocessing step
You can examine `tmp_preprocess__filename` and `tmp_mako__filename`,
@@ -4109,6 +4151,15 @@
### Problems with HTML Output
+#### MathJax formulas are not properly rendered
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ * `[` and `]` brackets must sometimes be replaced by `\lbrack` and
`\rbrack`
+
#### How can I change the layout of the HTML page?
The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /doc/demos/manual/manual.mwiki Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.mwiki Fri Jun 28 09:22:02 2013
@@ -1,7 +1,7 @@
#TITLE (actually governed by the filename): Doconce Description
By '''Hans Petter Langtangen'''
-==== May 29, 2013 ====
+==== Jun 28, 2013 ====
<!-- lines beginning with # are doconce comment lines -->
<!-- (documents can also have mako comment lines) -->
@@ -549,7 +549,7 @@
Transformation of a Doconce document <code>mydoc.do.txt</code> to various
other
-formats applies the script <code>doconce format</code>:
+formats apply the script <code>doconce format</code>:
<syntaxhighlight lang="bash">
Terminal> doconce format format mydoc.do.txt
</syntaxhighlight>
@@ -2106,7 +2106,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with <code>===</code> heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in <code>html</code> output such that search engines can make use of
the them.
==== Bibliography ====
@@ -2275,6 +2279,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes <code>|</code> can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+<syntaxhighlight lang="text">
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+</syntaxhighlight>
+
Note that not all formats offer alignment of heading or entries
in tables (<code>rst</code> and <code>sphinx</code> are examples). Also
note that
Doconce tables are very simple: neither entries nor
@@ -2287,6 +2304,33 @@
where <code>X</code> is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the <code>doconce csv2table</code> utility:
+
+<syntaxhighlight lang="bash">
+Terminal> doconce csv2table somefile.csv > table.do.txt
+</syntaxhighlight>
+This is a quick way of writing tables. For example, we can
+write a text file <code>tmp.csv</code> with
+
+<syntaxhighlight lang="python">
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+</syntaxhighlight>
+Running <code>doconce csv2table tmp.csv</code> creates the table
+
+<syntaxhighlight lang="text">
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+</syntaxhighlight>
+
==== Exercises, Problems, Projects, and Examples ====
Doconce has special support for four types of "exercises", named
@@ -2686,13 +2730,6 @@
\end{align}
!et
</syntaxhighlight>
-Here is the result:
-
-:<math>
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, \\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. \end{align}
-</math>
The support of LaTeX mathematics varies among the formats:
@@ -2789,58 +2826,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-''Example.''
-Suppose we have the following commands in
-<code>newcommand_replace.tex</code>:
-
-<syntaxhighlight lang="text">
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-</syntaxhighlight>
-
-and these in <code>newcommands_keep.tex</code>:
-
-<syntaxhighlight lang="text">
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-</syntaxhighlight>
-
-The LaTeX block
-<syntaxhighlight lang="text">
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-</syntaxhighlight>
-will then be rendered to
-:<math>
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, \\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } \end{eqnarray}
-</math>
-in the current format.
==== Admonitions ====
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-<code>block</code>, <code>warning</code>, <code>notice</code>,
<code>hint</code>, <code>question</code>, and <code>summary</code>.
-The box is defined by begin and end tags such as <code>!bhint</code> and
<code>!ehint</code>.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading ''Hint'' (with number)
-appears, while outside exercises the <code>hint</code> environment gives a
-box with some admonition icon, text and/or colored background.)
+<code>block</code>, <code>warning</code>, <code>notice</code>,
<code>question</code>, and <code>summary</code>.
+The box is defined by begin and end tags such as <code>!bnotice</code> and
<code>!enotice</code>.
The title of the box is fully customizable.
Here are a few examples:
@@ -2850,9 +2848,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3253,7 +3251,9 @@
<!-- doconce-adjusted styles: easy to switch between styles since -->
<!-- font sizes are compatible -->
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
<syntaxhighlight lang="bash">
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3272,6 +3272,16 @@
==== LaTeX Beamer Slides ====
+Not yet written...
+
+==== Themes ====
+
+Four themes come with Doconce: <code>X_Y</code>, where <code>X</code> is
<code>blue</code> or <code>red</code>
+(the main color of the slides) and <code>Y</code> is
[http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf
<code>plain</code>]
+for simple layout and
+[http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf
<code>shadow</code>]
+for shadowed boxes and more visual structure in the slides.
+
== Mako Programming ==
The [http://docs.makotemplates.org/ Mako] templating engine is used
@@ -3281,6 +3291,18 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+{{mbox
+| type = warning
+| textstyle = font-size: 90%;
+| text = '''Warning.''' Unfortunately, the combination of Mako and LaTeX
mathematics may
+lead to problems because Mako applies syntax like <code>${var}</code> to
extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., <code>${\cal O}(\Delta x^2)$</code> which looks
like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+}}
+
==== The Basics of Mako ====
Just a preliminary sketch of some Mako code (next example is better!):
@@ -3455,6 +3477,15 @@
==== General Problems ====
+==== Spellcheck reports a lot of mistakes related LaTeX math ====
+
+The <code>doconce spellcheck</code> command should ignore LaTeX math, but
if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant <code>tmp_missing_*</code> file and search for the math
expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
==== Doconce aborts because of a syntax error that is not an error ====
Doconce searches for typical syntax errors and usually aborts the
@@ -3482,6 +3513,26 @@
to <code>'T < %.1f'</code> to avoid this confusion.
</ul>
+==== The Mako preprocessor claims a variable is undefined ====
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, <math>{\cal O}(\Delta x^2)</math> is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use <code>${</code> anywhere in LaTeX
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is <code>${}^+$</code> type of indication of
superscripts.
+A suggested rewrite is <code>$\,{}^+$</code>.
+
+The error message will ask you to rerun <code>doconce</code> with
+<code>--mako_strict_undefined</code>, which will display the variable that
+is confusing Mako. However, do not continue to use
+<code>--mako_strict_undefined</code> while you are debugging because this
+variable will then always be undefined in that mode.
+Use <code># #ifdef</code> directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without <code>--mako_strict_undefined</code>).
+
==== Something goes wrong in the preprocessing step ====
You can examine <code>tmp_preprocess__filename</code> and
<code>tmp_mako__filename</code>,
@@ -3870,6 +3921,17 @@
==== Problems with HTML Output ====
+==== MathJax formulas are not properly rendered ====
+
+Here are some common problems:
+
+
+<ul>
+ <li> Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+ <li> <code>[</code> and <code>]</code> brackets must sometimes be
replaced by <code>\lbrack</code> and <code>\rbrack</code>
+</ul>
+
==== How can I change the layout of the HTML page? ====
The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /doc/demos/manual/manual.p.tex Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.p.tex Fri Jun 28 09:22:02 2013
@@ -116,10 +116,11 @@
% #endif
% Hyperlinks in PDF:
+\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage[%
colorlinks=true,
- linkcolor=blue,
- urlcolor=blue,
+ linkcolor=linkcolor,
+ urlcolor=linkcolor,
citecolor=black,
filecolor=black,
%filecolor=blue,
@@ -168,10 +169,10 @@
% Admonition is an oval gray box
\newmdenv[
- backgroundcolor=gray!10, %% white with 10%% gray
+ backgroundcolor=gray!5, %% white with 5%% gray
skipabove=\topsep,
skipbelow=\topsep,
- outerlinewidth=0.5,
+ outerlinewidth=0,
leftmargin=0,
rightmargin=0,
roundcorner=5,
@@ -317,16 +318,16 @@
% #if LATEX_HEADING == "traditional"
-\date{May 29, 2013}
+\date{Jun 28, 2013}
\maketitle
% #elif LATEX_HEADING == "beamer"
-\date{May 29, 2013
+\date{Jun 28, 2013
% <titlepage figure>
}
% #elif LATEX_HEADING == "titlepage"
\ \\ [10mm]
-{\large\textsf{May 29, 2013}}
+{\large\textsf{Jun 28, 2013}}
\end{center}
\vfill
@@ -334,7 +335,7 @@
% #else
\begin{center}
-May 29, 2013
+Jun 28, 2013
\end{center}
\vspace{1cm}
@@ -896,7 +897,7 @@
\label{doconce2formats}
Transformation of a Doconce document \code{mydoc.do.txt} to various other
-formats applies the script \code{doconce format}:
+formats apply the script \code{doconce format}:
\bsys
Terminal> doconce format format mydoc.do.txt
\esys
@@ -1083,6 +1084,7 @@
code with MathJax
scripts so there is no support for mathematics in the discussion forum.
\end{graybox1admon}
+
\begin{graybox1admon}[Notice.]
Figure files must be uploaded to some web site and the filenames name must
be replaced by the relevant URL. This can be automatically edited:
@@ -1099,6 +1101,7 @@
# Paste mydoc2.html into a new blog page
\eshcod
\end{graybox1admon}
+
Blog posts at Google can also be published
\href{{http://support.google.com/blogger/bin/answer.py?hl=en&answer=41452}}{automatically
through email}.
A Python program can send the contents of the HTML file
to the blog's email address using the packages \code{smtplib} and
\code{email}.
@@ -2211,6 +2214,7 @@
becomes correct (sometimes a trial and error process - sticking to
very simple formatting usually avoids such problems).
\end{graybox1admon}
+
\paragraph{Links to Web Addresses.}
Web addresses with links are typeset as
\bccq
@@ -2530,7 +2534,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-{\LaTeX} is the output format).
+{\LaTeX} is the output format). For paragraphs with \code{===} heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in \code{html} output such that search engines can make use of the
them.
\subsection{Bibliography}
@@ -2571,6 +2579,7 @@
curly braces. You may need to edit your \textsc{Bib}\negthinspace{\TeX}
files to meet this
demand.
\end{graybox1admon}
+
The utility \code{doconce fix_bibtex4publish file.bib} fixes several known
issues with \textsc{Bib}\negthinspace{\TeX} files such that Publish has a
better chance of
accepting the entries. Run this utility first, then run Publish,
@@ -2695,6 +2704,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes \code{|} can also be inserted to indicate
vertical rules in {\LaTeX} tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+\bccq
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+\eccq
+
Note that not all formats offer alignment of heading or entries
in tables (\code{rst} and \code{sphinx} are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2707,6 +2729,33 @@
where \code{X} is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the \code{doconce csv2table} utility:
+
+\bsys
+Terminal> doconce csv2table somefile.csv > table.do.txt
+\esys
+This is a quick way of writing tables. For example, we can
+write a text file \code{tmp.csv} with
+
+\bdat
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+\edat
+Running \code{doconce csv2table tmp.csv} creates the table
+
+\bccq
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+\eccq
+
\subsection{Exercises, Problems, Projects, and Examples}
Doconce has special support for four types of "exercises", named
@@ -3108,12 +3157,6 @@
\end{align}
!et
\eccq
-Here is the result:
-
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, \label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. \label{myeq2}
-\end{align}
The support of {\LaTeX} mathematics varies among the formats:
@@ -3218,57 +3261,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-\paragraph{Example.}
-Suppose we have the following commands in
-\code{newcommand_replace.tex}:
-
-\blatexpro
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-\elatexpro
-
-and these in \code{newcommands_keep.tex}:
-
-\blatexpro
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-\elatexpro
-
-The {\LaTeX} block
-\bccq
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-\eccq
-will then be rendered to
-\beqa
-\x\cdot\normalvec &=& 0, \label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep \label{my:eq2}
-\eeqa
-in the current format.
\subsection{Admonitions}
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-\code{block}, \code{warning}, \code{notice}, \code{hint}, \code{question},
and \code{summary}.
-The box is defined by begin and end tags such as \code{!bhint} and
\code{!ehint}.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading \emph{Hint} (with number)
-appears, while outside exercises the \code{hint} environment gives a
-box with some admonition icon, text and/or colored background.)
+\code{block}, \code{warning}, \code{notice}, \code{question}, and
\code{summary}.
+The box is defined by begin and end tags such as \code{!bnotice} and
\code{!enotice}.
The title of the box is fully customizable.
Here are a few examples:
@@ -3278,9 +3283,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3304,17 +3309,21 @@
\begin{graybox1admon}[Warning.]
Here is a warning!
\end{graybox1admon}
+
\begin{graybox1admon}[Hint.]
This is a hint.
\end{graybox1admon}
+
\begin{graybox1admon}[This is a block.]
A block has never any icon.
\end{graybox1admon}
+
\begin{graybox1admon}[Going deeper.]
This is text meant to provide more details. The box has the
layout of the notice box, but a custom title, here "Going deeper".
\end{graybox1admon}
+
Finally some summary:
@@ -3322,6 +3331,7 @@
The main message is to utilize the admonition styles for
marking different parts of the text
\end{graybox1admon}
+
The layout of admonitions depend on the format.
In \code{rst} and \code{sphinx} one applies the native admonitions, but
in \code{sphinx} the \code{automake_sphinx.py} script manipulates the HTML
@@ -3592,6 +3602,7 @@
\subsection{Emacs Doconce Formatter}
\label{emacs:doconce}
+
The file
\href{{https://doconce.googlecode.com/hg/misc/.doconce-mode.el}}{.doconce-mode.el}
in the Doconce source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3697,7 +3708,9 @@
% doconce-adjusted styles: easy to switch between styles since
% font sizes are compatible
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
\bsys
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3716,6 +3729,15 @@
\noindent
\subsection{{\LaTeX} Beamer Slides}
+
+Not yet written...
+
+\paragraph{Themes.}
+Four themes come with Doconce: \code{X_Y}, where \code{X} is \code{blue}
or \code{red}
+(the main color of the slides) and \code{Y} is
\href{{http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf}}{\nolinkurl{plain}}
+for simple layout and
+\href{{http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf}}{\nolinkurl{shadow}}
+for shadowed boxes and more visual structure in the slides.
\section{Mako Programming}
@@ -3726,6 +3748,16 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+\begin{graybox1admon}[Warning.]
+Unfortunately, the combination of Mako and {\LaTeX} mathematics may
+lead to problems because Mako applies syntax like \code{${var}} to extract
+variables or call functions, while {\LaTeX} mathematics sometimes applies
+the same syntax, e.g., \code{${\cal O}(\Delta x^2)$} which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+\end{graybox1admon}
+
\subsection{The Basics of Mako}
Just a preliminary sketch of some Mako code (next example is better!):
@@ -3900,6 +3932,14 @@
\subsection{General Problems}
+
+\paragraph{Spellcheck reports a lot of mistakes related {\LaTeX} math.}
+The \code{doconce spellcheck} command should ignore {\LaTeX} math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant \code{tmp_missing_*} file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
\paragraph{Doconce aborts because of a syntax error that is not an error.}
Doconce searches for typical syntax errors and usually aborts the
@@ -3925,6 +3965,25 @@
\end{itemize}
\noindent
+\paragraph{The Mako preprocessor claims a variable is undefined.}
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired {\LaTeX} syntax.
+For example, ${\cal O}(\Delta x^2)$ is valid {\LaTeX}, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use \code{${} anywhere in {\LaTeX}
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is \code{${}^+$} type of indication of superscripts.
+A suggested rewrite is \code{$\,{}^+$}.
+
+The error message will ask you to rerun \code{doconce} with
+\code{--mako_strict_undefined}, which will display the variable that
+is confusing Mako. However, do not continue to use
+\code{--mako_strict_undefined} while you are debugging because this
+variable will then always be undefined in that mode.
+Use \code{# #ifdef} directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without \code{--mako_strict_undefined}).
+
\paragraph{Something goes wrong in the preprocessing step.}
You can examine \code{tmp_preprocess__filename} and
\code{tmp_mako__filename},
where \code{filename} is the complete name of the Doconce file, to see
@@ -4157,7 +4216,7 @@
When this package is included, \code{latex} or \code{pdflatex} runs the
\code{pygmentize} program and the \code{shell-escape} option is required.
-\paragraph{Why are the {\LaTeX} section headings smaller than normal?.}
+\paragraph{Why are the {\LaTeX} section headings smaller than normal?}
Doconce inserts a special command to make the headings
more compact:
@@ -4176,7 +4235,7 @@
by replacing \code{[compact]} by \code{[compact,small]} as parameter
specification
for \code{titlesec}.
-\paragraph{Can I have {\LaTeX} figures with shadows?.}
+\paragraph{Can I have {\LaTeX} figures with shadows?}
This is easy by including the \code{fancybox} and \code{graphicx} packages
and wrapping all \code{\includegraphics} in a shadow box:
@@ -4188,7 +4247,7 @@
'\\shadowbox{\g<1>}' mydoc.p.tex
\esys
-\paragraph{How can I use my fancy {\LaTeX} environments?.}
+\paragraph{How can I use my fancy {\LaTeX} environments?}
See Section~\ref{manual:theorem:envir} for how to make a custom
theorem environment also in Doconce, without using implementations
restricted to {\LaTeX}.
@@ -4276,7 +4335,18 @@
\subsection{Problems with HTML Output}
-\paragraph{How can I change the layout of the HTML page?.}
+\paragraph{MathJax formulas are not properly rendered.}
+Here are some common problems:
+
+\begin{itemize}
+ \item Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ \item \code{[} and \code{]} brackets must sometimes be replaced by
\code{\lbrack} and \code{\rbrack}
+\end{itemize}
+
+\noindent
+\paragraph{How can I change the layout of the HTML page?}
The easiest way is to edit the HTML style or the HTML code directly.
However, those edits are overwritten the next time you compile the
Doconce document to HTML. The edits should therefore be automated
@@ -4313,7 +4383,7 @@
use the \code{sphinx} format and one its many themes.
-\paragraph{Why do figures look ugly when using HTML templates?.}
+\paragraph{Why do figures look ugly when using HTML templates?}
The HTML header that Doconce generates contain special styles for
figure captions and the horizontal rule above figures. When using
templates these styles are not defined, resulting in a rule that
=======================================
--- /doc/demos/manual/manual.pdf Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.pdf Fri Jun 28 09:22:02 2013
Binary file, no diff available.
=======================================
--- /doc/demos/manual/manual.rst Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.rst Fri Jun 28 09:22:02 2013
@@ -5,7 +5,7 @@
===================
:Author: Hans Petter Langtangen
-:Date: May 29, 2013
+:Date: Jun 28, 2013
.. lines beginning with # are doconce comment lines
@@ -598,7 +598,7 @@
=============================
Transformation of a Doconce document ``mydoc.do.txt`` to various other
-formats applies the script ``doconce format``::
+formats apply the script ``doconce format``::
Terminal> doconce format format mydoc.do.txt
@@ -2271,7 +2271,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with ``===`` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in ``html`` output such that search engines can make use of the them.
Bibliography (2)
-----------------
@@ -2450,6 +2454,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes ``|`` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like::
+
+
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+
+
Note that not all formats offer alignment of heading or entries
in tables (``rst`` and ``sphinx`` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2462,6 +2479,33 @@
where ``X`` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the ``doconce csv2table`` utility::
+
+
+ Terminal> doconce csv2table somefile.csv > table.do.txt
+
+This is a quick way of writing tables. For example, we can
+write a text file ``tmp.csv`` with::
+
+
+ time, velocity, acceleration
+ 0.0, 1.4186, -5.01
+ 2.0, 1.376512, 11.919
+ 4.0, 1.1E+1, 14.717624
+
+Running ``doconce csv2table tmp.csv`` creates the table::
+
+
+ |------c--------------c--------------c-------|
+ | time | velocity | acceleration |
+ |------c--------------c--------------c-------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------------------|
+
+
Exercises, Problems, Projects, and Examples
-------------------------------------------
@@ -2883,13 +2927,6 @@
\end{align}
!et
-Here is the result::
-
- \begin{align}
- {\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
- {\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
- \end{align}
-
The support of LaTeX mathematics varies among the formats:
@@ -2991,61 +3028,21 @@
newcommands in the ``newcommands*.tex`` files *must* appear on a single
line (multi-line newcommands are too hard to parse with regular
expressions).
-
-*Example.* Suppose we have the following commands in
-``newcommand_replace.tex``::
-
-
- \newcommand{\beqa}{\begin{eqnarray}}
- \newcommand{\eeqa}{\end{eqnarray}}
- \newcommand{\ep}{\thinspace . }
- \newcommand{\uvec}{\vec u}
- \newcommand{\Q}{\pmb{Q}}
-and these in ``newcommands_keep.tex``::
-
-
- \newcommand{\x}{\pmb{x}}
- \newcommand{\normalvec}{\pmb{n}}
- \newcommand{\Ddt}[1]{\frac{D#1}{dt}}
- \newcommand{\half}{\frac{1}{2}}
-
-
-The LaTeX block::
-
-
- \beqa
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{\uvec} &=& \Q \ep label{my:eq2}
- \eeqa
-
-will then be rendered to::
-
- \begin{eqnarray}
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
- \end{eqnarray}
-
-in the current format.
-
Admonitions
-----------
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-``block``, ``warning``, ``notice``, ``hint``, ``question``, and
``summary``.
-The box is defined by begin and end tags such as ``!bhint`` and ``!ehint``.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the ``hint`` environment gives a
-box with some admonition icon, text and/or colored background.)
+``block``, ``warning``, ``notice``, ``question``, and ``summary``.
+The box is defined by begin and end tags such as ``!bnotice`` and
``!enotice``.
The title of the box is fully customizable.
Here are a few examples::
@@ -3055,9 +3052,9 @@
Here is a warning!
!ewarning
- !bhint
+ !bnotice Hint
This is a hint.
- !ehint
+ !enotice
!bblock This is a block.
A block has never any icon.
@@ -3082,7 +3079,8 @@
Here is a warning!
-.. hint::
+.. admonition:: Hint
+
This is a hint.
@@ -3376,6 +3374,7 @@
Emacs Doconce Formatter
-----------------------
+
The file `.doconce-mode.el
<https://doconce.googlecode.com/hg/misc/.doconce-mode.el>`_ in the Doconce
source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3476,7 +3475,9 @@
.. font sizes are compatible
-Text is missing... Just a very preliminary sketch of commands::
+Not yet written...
+
+Just a very preliminary sketch of commands::
Terminal> doconce format html myslides \
@@ -3497,6 +3498,17 @@
LaTeX Beamer Slides
-------------------
+Not yet written...
+
+Themes
+~~~~~~
+
+Four themes come with Doconce: ``X_Y``, where ``X`` is ``blue`` or ``red``
+(the main color of the slides) and ``Y`` is `plain
<http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf>`_
+for simple layout and
+`shadow
<http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf>`_
+for shadowed boxes and more visual structure in the slides.
+
Mako Programming
================
@@ -3507,6 +3519,16 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+.. warning::
+ Unfortunately, the combination of Mako and LaTeX mathematics may
+ lead to problems because Mako applies syntax like ``${var}`` to extract
+ variables or call functions, while LaTeX mathematics sometimes applies
+ the same syntax, e.g., ``${\cal O}(\Delta x^2)$`` which looks like a
+ Mako function call. This problem can give rise to strange error
+ messages from Mako, usually that a variable is not defined.
+
+
The Basics of Mako
------------------
@@ -3691,6 +3713,16 @@
General Problems
----------------
+Spellcheck reports a lot of mistakes related LaTeX math
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``doconce spellcheck`` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant ``tmp_missing_*`` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
Doconce aborts because of a syntax error that is not an error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3718,6 +3750,27 @@
* Strings with ``'T<%.1f'`` look as openings of Mako blocks (``<%``);
change
to ``'T < %.1f'`` to avoid this confusion.
+The Mako preprocessor claims a variable is undefined
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, {\cal O}(\Delta x^2) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use ``${`` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is ``${}^+$`` type of indication of superscripts.
+A suggested rewrite is ``$\,{}^+$``.
+
+The error message will ask you to rerun ``doconce`` with
+``--mako_strict_undefined``, which will display the variable that
+is confusing Mako. However, do not continue to use
+``--mako_strict_undefined`` while you are debugging because this
+variable will then always be undefined in that mode.
+Use ``# #ifdef`` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without ``--mako_strict_undefined``).
+
Something goes wrong in the preprocessing step
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4159,6 +4212,16 @@
Problems with HTML Output
-------------------------
+MathJax formulas are not properly rendered
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ * ``[`` and ``]`` brackets must sometimes be replaced by ``\lbrack`` and
``\rbrack``
+
How can I change the layout of the HTML page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================
--- /doc/demos/manual/manual.rst.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.rst.html Fri Jun 28 09:22:02 2013
@@ -327,7 +327,7 @@
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td
class="field-body">Hans Petter Langtangen</td>
</tr>
-<tr class="field"><th class="field-name">Date:</th><td
class="field-body">May 29, 2013</td>
+<tr class="field"><th class="field-name">Date:</th><td
class="field-body">Jun 28, 2013</td>
</tr>
</tbody>
</table>
@@ -846,7 +846,7 @@
<div class="section" id="from-doconce-to-other-formats">
<span id="doconce2formats"></span><h1>From Doconce to Other Formats</h1>
<p>Transformation of a Doconce document <tt class="docutils
literal">mydoc.do.txt</tt> to various other
-formats applies the script <tt class="docutils literal">doconce
format</tt>:</p>
+formats apply the script <tt class="docutils literal">doconce
format</tt>:</p>
<pre class="literal-block">
Terminal> doconce format format mydoc.do.txt
</pre>
@@ -2246,7 +2246,10 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).</p>
+LaTeX is the output format). For paragraphs with <tt class="docutils
literal">===</tt> heading,
+the index keywords should be placed above the heading.</p>
+<p>The keywords in the index are automatically placed in a meta
+tag in <tt class="docutils literal">html</tt> output such that search
engines can make use of the them.</p>
</div>
<div class="section" id="bibliography-2">
<h2>Bibliography (2)</h2>
@@ -2422,7 +2425,18 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes <tt class="docutils literal">|</tt> can also be
inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
-Note that not all formats offer alignment of heading or entries
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like:</p>
+<pre class="literal-block">
+|--c--------c-----------c--------|
+|time | velocity | acceleration |
+|--l--------r-----------r--------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------|
+</pre>
+<p>Note that not all formats offer alignment of heading or entries
in tables (<tt class="docutils literal">rst</tt> and <tt class="docutils
literal">sphinx</tt> are examples). Also note that
Doconce tables are very simple: neither entries nor
headings can span several columns or rows. When that functionality
@@ -2432,6 +2446,29 @@
makes Doconce dump each table to CSV format in a file <tt class="docutils
literal">table_X.csv</tt>,
where <tt class="docutils literal">X</tt> is the table number. This
feature makes it easy to
load tables into spreadsheet programs for further analysis.</p>
+<p>Data in CSV format can be transformed to Doconce table format
+by the <tt class="docutils literal">doconce csv2table</tt> utility:</p>
+<pre class="literal-block">
+Terminal> doconce csv2table somefile.csv > table.do.txt
+</pre>
+<p>This is a quick way of writing tables. For example, we can
+write a text file <tt class="docutils literal">tmp.csv</tt> with:</p>
+<pre class="literal-block">
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+</pre>
+<p>Running <tt class="docutils literal">doconce csv2table tmp.csv</tt>
creates the table:</p>
+<pre class="literal-block">
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+</pre>
</div>
<div class="section" id="exercises-problems-projects-and-examples">
<h2>Exercises, Problems, Projects, and Examples</h2>
@@ -2800,13 +2837,6 @@
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
\end{align}
!et
-</pre>
-<p>Here is the result:</p>
-<pre class="literal-block">
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
-\end{align}
</pre>
<p>The support of LaTeX mathematics varies among the formats:</p>
<blockquote>
@@ -2897,53 +2927,18 @@
newcommands in the <tt class="docutils literal"><span
class="pre">newcommands*.tex</span></tt> files <em>must</em> appear on a
single
line (multi-line newcommands are too hard to parse with regular
expressions).</p>
-<p><em>Example.</em> Suppose we have the following commands in
-<tt class="docutils literal">newcommand_replace.tex</tt>:</p>
-<pre class="literal-block">
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-</pre>
-<p>and these in <tt class="docutils literal">newcommands_keep.tex</tt>:</p>
-<pre class="literal-block">
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-</pre>
-<p>The LaTeX block:</p>
-<pre class="literal-block">
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-</pre>
-<p>will then be rendered to:</p>
-<pre class="literal-block">
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
-\end{eqnarray}
-</pre>
-<p>in the current format.</p>
</div>
<div class="section" id="admonitions">
<h2>Admonitions</h2>
<p>Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.</p>
<p>The following admonition environments are available:
-<tt class="docutils literal">block</tt>, <tt class="docutils
literal">warning</tt>, <tt class="docutils literal">notice</tt>, <tt
class="docutils literal">hint</tt>, <tt class="docutils
literal">question</tt>, and <tt class="docutils literal">summary</tt>.
-The box is defined by begin and end tags such as <tt class="docutils
literal">!bhint</tt> and <tt class="docutils literal">!ehint</tt>.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading <em>Hint</em> (with number)
-appears, while outside exercises the <tt class="docutils
literal">hint</tt> environment gives a
-box with some admonition icon, text and/or colored background.)
+<tt class="docutils literal">block</tt>, <tt class="docutils
literal">warning</tt>, <tt class="docutils literal">notice</tt>, <tt
class="docutils literal">question</tt>, and <tt class="docutils
literal">summary</tt>.
+The box is defined by begin and end tags such as <tt class="docutils
literal">!bnotice</tt> and <tt class="docutils literal">!enotice</tt>.
The title of the box is fully customizable.</p>
<p>Here are a few examples:</p>
<pre class="literal-block">
@@ -2951,9 +2946,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -2976,7 +2971,7 @@
<p class="first admonition-title">Warning</p>
<p class="last">Here is a warning!</p>
</div>
-<div class="hint">
+<div class="admonition-hint admonition">
<p class="first admonition-title">Hint</p>
<p class="last">This is a hint.</p>
</div>
@@ -3348,7 +3343,8 @@
<h2>HTML5 Slides</h2>
<!-- doconce-adjusted styles: easy to switch between styles since -->
<!-- font sizes are compatible -->
-<p>Text is missing... Just a very preliminary sketch of commands:</p>
+<p>Not yet written...</p>
+<p>Just a very preliminary sketch of commands:</p>
<pre class="literal-block">
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3369,12 +3365,21 @@
</div>
<div class="section" id="latex-beamer-slides">
<h2>LaTeX Beamer Slides</h2>
+<p>Not yet written...</p>
+<div class="section" id="themes">
+<h3>Themes</h3>
+<p>Four themes come with Doconce: <tt class="docutils literal">X_Y</tt>,
where <tt class="docutils literal">X</tt> is <tt class="docutils
literal">blue</tt> or <tt class="docutils literal">red</tt>
+(the main color of the slides) and <tt class="docutils literal">Y</tt> is
<a class="reference external"
href="http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf">plain</a>
+for simple layout and
+<a class="reference external"
href="http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf">shadow</a>
+for shadowed boxes and more visual structure in the slides.</p>
+</div>
</div>
</div>
<div class="section" id="mako-programming">
<h1>Mako Programming</h1>
<div class="system-message">
-<p class="system-message-title">System Message: WARNING/2 (<tt
class="docutils">manual.rst</tt>, line 3501); <em><a
href="#id15">backlink</a></em></p>
+<p class="system-message-title">System Message: WARNING/2 (<tt
class="docutils">manual.rst</tt>, line 3513); <em><a
href="#id15">backlink</a></em></p>
Duplicate explicit target name: "mako".</div>
<p>The <a class="reference external"
href="http://docs.makotemplates.org/">Mako</a> templating engine is used
as preprocessor for Doconce documents, but the <a class="reference
external" href="http://code.google.com/p/preprocess">Preprocess</a> is run
prior to Mako and is recommended for
@@ -3382,6 +3387,15 @@
sufficient for if-else tests to steer which parts of the text that
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.</p>
+<div class="warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Unfortunately, the combination of Mako and LaTeX
mathematics may
+lead to problems because Mako applies syntax like <tt class="docutils
literal">${var}</tt> to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., <tt class="docutils literal"><span
class="pre">${\cal</span> <span class="pre">O}(\Delta</span> x^2)$</tt>
which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.</p>
+</div>
<div class="section" id="the-basics-of-mako">
<h2>The Basics of Mako</h2>
<p>Just a preliminary sketch of some Mako code (next example is
better!):</p>
@@ -3549,6 +3563,15 @@
</div>
<div class="section" id="general-problems">
<h2>General Problems</h2>
+<div class="section"
id="spellcheck-reports-a-lot-of-mistakes-related-latex-math">
+<h3>Spellcheck reports a lot of mistakes related LaTeX math</h3>
+<p>The <tt class="docutils literal">doconce spellcheck</tt> command should
ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant <tt class="docutils literal">tmp_missing_*</tt> file and search
for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.</p>
+</div>
<div class="section"
id="doconce-aborts-because-of-a-syntax-error-that-is-not-an-error">
<h3>Doconce aborts because of a syntax error that is not an error</h3>
<p>Doconce searches for typical syntax errors and usually aborts the
@@ -3576,6 +3599,25 @@
</ul>
</blockquote>
</div>
+<div class="section"
id="the-mako-preprocessor-claims-a-variable-is-undefined">
+<h3>The Mako preprocessor claims a variable is undefined</h3>
+<p>Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, {cal O}(Delta x^2) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use <tt class="docutils literal">${</tt>
anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is <tt class="docutils literal"><span
class="pre">${}^+$</span></tt> type of indication of superscripts.
+A suggested rewrite is <tt class="docutils literal"><span
class="pre">$\,{}^+$</span></tt>.</p>
+<p>The error message will ask you to rerun <tt class="docutils
literal">doconce</tt> with
+<tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt>, which will display the
variable that
+is confusing Mako. However, do not continue to use
+<tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt> while you are debugging
because this
+variable will then always be undefined in that mode.
+Use <tt class="docutils literal"># #ifdef</tt> directives to comment out
large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without <tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt>).</p>
+</div>
<div class="section" id="something-goes-wrong-in-the-preprocessing-step">
<h3>Something goes wrong in the preprocessing step</h3>
<p>You can examine <tt class="docutils
literal">tmp_preprocess__filename</tt> and <tt class="docutils
literal">tmp_mako__filename</tt>,
@@ -3952,6 +3994,17 @@
</div>
<div class="section" id="problems-with-html-output">
<h2>Problems with HTML Output</h2>
+<div class="section" id="mathjax-formulas-are-not-properly-rendered">
+<h3>MathJax formulas are not properly rendered</h3>
+<p>Here are some common problems:</p>
+<blockquote>
+<ul class="simple">
+<li>Two equations cannot have identical label (this error often arises
+from copying and pasting equations)</li>
+<li><tt class="docutils literal">[</tt> and <tt class="docutils
literal">]</tt> brackets must sometimes be replaced by <tt class="docutils
literal">\lbrack</tt> and <tt class="docutils literal">\rbrack</tt></li>
+</ul>
+</blockquote>
+</div>
<div class="section" id="how-can-i-change-the-layout-of-the-html-page">
<h3>How can I change the layout of the HTML page?</h3>
<p>The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /doc/demos/manual/manual.rst.pdf Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.rst.pdf Fri Jun 28 09:22:02 2013
Binary file, no diff available.
=======================================
--- /doc/demos/manual/manual.rst.tex Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.rst.tex Fri Jun 28 09:22:02 2013
@@ -82,7 +82,7 @@
Hans Petter Langtangen
\item[{Date:}]
-May 29, 2013
+Jun 28, 2013
\end{DUfieldlist}
@@ -899,7 +899,7 @@
}
Transformation of a Doconce document \texttt{mydoc.do.txt} to various other
-formats applies the script \texttt{doconce format}:
+formats apply the script \texttt{doconce format}:
%
\begin{quote}{\ttfamily \raggedright \noindent
Terminal>~doconce~format~format~mydoc.do.txt
@@ -2980,7 +2980,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with \texttt{===} heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in \texttt{html} output such that search engines can make use of the
them.
%___________________________________________________________________________
@@ -3269,6 +3273,20 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes \texttt{|} can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like:
+%
+\begin{quote}{\ttfamily \raggedright \noindent
+|
-{}-c-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-|
\\
+|time~~|~velocity~|~acceleration~|\\
+|
-{}-l-{}-{}-{}-{}-{}-{}-{}-r-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-r-{}-{}-{}-{}-{}-{}-{}-|
\\
+|~0.0~~|~1.4186~~~|~-5.01~~~~~~~~|\\
+|~2.0~~|~1.376512~|~11.919~~~~~~~|\\
+|~4.0~~|~1.1E+1~~~|~14.717624~~~~|\\
+|
-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-|
+}
+\end{quote}
+
Note that not all formats offer alignment of heading or entries
in tables (\texttt{rst} and \texttt{sphinx} are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -3281,6 +3299,38 @@
where \texttt{X} is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the \texttt{doconce csv2table} utility:
+%
+\begin{quote}{\ttfamily \raggedright \noindent
+Terminal>~doconce~csv2table~somefile.csv~>~table.do.txt
+}
+\end{quote}
+
+This is a quick way of writing tables. For example, we can
+write a text file \texttt{tmp.csv} with:
+%
+\begin{quote}{\ttfamily \raggedright \noindent
+time,~velocity,~acceleration\\
+0.0,~1.4186,~-5.01\\
+2.0,~1.376512,~11.919\\
+4.0,~1.1E+1,~14.717624
+}
+\end{quote}
+
+Running \texttt{doconce csv2table tmp.csv} creates the table:
+%
+\begin{quote}{\ttfamily \raggedright \noindent
+|
-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-|
\\
+|~time~~~~~~~~~|~velocity~~~~~|~acceleration~|\\
+|
-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-|
\\
+|~0.0~~~~~~~~~~|~1.4186~~~~~~~|~-5.01~~~~~~~~|\\
+|~2.0~~~~~~~~~~|~1.376512~~~~~|~11.919~~~~~~~|\\
+|~4.0~~~~~~~~~~|~1.1E+1~~~~~~~|~14.717624~~~~|\\
+|
-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-|
+}
+\end{quote}
+
%___________________________________________________________________________
@@ -3736,16 +3786,6 @@
!et
}
\end{quote}
-
-Here is the result:
-%
-\begin{quote}{\ttfamily \raggedright \noindent
-\textbackslash{}begin\{align\}\\
-\{\textbackslash{}partial~u\textbackslash{}over\textbackslash{}partial~t\}~\&=~\textbackslash{}nabla\textasciicircum{}2~u~+~f,~label\{myeq1\}\textbackslash{}\textbackslash{}\\
-\{\textbackslash{}partial~v\textbackslash{}over\textbackslash{}partial~t\}~\&=~\textbackslash{}nabla\textbackslash{}cdot(q(u)\textbackslash{}nabla~v)~+~g.~label\{myeq2\}\\
-\textbackslash{}end\{align\}
-}
-\end{quote}
The support of LaTeX mathematics varies among the formats:
%
@@ -3878,50 +3918,6 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-\emph{Example.} Suppose we have the following commands in
-\texttt{newcommand\_replace.tex}:
-%
-\begin{quote}{\ttfamily \raggedright \noindent
-\textbackslash{}newcommand\{\textbackslash{}beqa\}\{\textbackslash{}begin\{eqnarray\}\}\\
-\textbackslash{}newcommand\{\textbackslash{}eeqa\}\{\textbackslash{}end\{eqnarray\}\}\\
-\textbackslash{}newcommand\{\textbackslash{}ep\}\{\textbackslash{}thinspace~.~\}\\
-\textbackslash{}newcommand\{\textbackslash{}uvec\}\{\textbackslash{}vec~u\}\\
-\textbackslash{}newcommand\{\textbackslash{}Q\}\{\textbackslash{}pmb\{Q\}\}
-}
-\end{quote}
-
-and these in \texttt{newcommands\_keep.tex}:
-%
-\begin{quote}{\ttfamily \raggedright \noindent
-\textbackslash{}newcommand\{\textbackslash{}x\}\{\textbackslash{}pmb\{x\}\}\\
-\textbackslash{}newcommand\{\textbackslash{}normalvec\}\{\textbackslash{}pmb\{n\}\}\\
-\textbackslash{}newcommand\{\textbackslash{}Ddt\}{[}1{]}\{\textbackslash{}frac\{D\#1\}\{dt\}\}\\
-\textbackslash{}newcommand\{\textbackslash{}half\}\{\textbackslash{}frac\{1\}\{2\}\}
-}
-\end{quote}
-
-The LaTeX block:
-%
-\begin{quote}{\ttfamily \raggedright \noindent
-\textbackslash{}beqa\\
-\textbackslash{}x\textbackslash{}cdot\textbackslash{}normalvec~\&=\&~0,~label\{my:eq1\}\textbackslash{}\textbackslash{}\\
-\textbackslash{}Ddt\{\textbackslash{}uvec\}~\&=\&~\textbackslash{}Q~\textbackslash{}ep~~~label\{my:eq2\}\\
-\textbackslash{}eeqa
-}
-\end{quote}
-
-will then be rendered to:
-%
-\begin{quote}{\ttfamily \raggedright \noindent
-\textbackslash{}begin\{eqnarray\}\\
-\textbackslash{}x\textbackslash{}cdot\textbackslash{}normalvec~\&=\&~0,~label\{my:eq1\}\textbackslash{}\textbackslash{}\\
-\textbackslash{}Ddt\{\{\textbackslash{}vec~u\}\}~\&=\&~\textbackslash{}pmb\{Q\}~\{\textbackslash{}thinspace~.~\}~~~label\{my:eq2\}\\
-\textbackslash{}end\{eqnarray\}
-}
-\end{quote}
-
-in the current format.
-
%___________________________________________________________________________
@@ -3932,19 +3928,15 @@
}
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-\texttt{block}, \texttt{warning}, \texttt{notice}, \texttt{hint},
\texttt{question}, and \texttt{summary}.
-The box is defined by begin and end tags such as \texttt{!bhint} and
\texttt{!ehint}.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading \emph{Hint} (with number)
-appears, while outside exercises the \texttt{hint} environment gives a
-box with some admonition icon, text and/or colored background.)
+\texttt{block}, \texttt{warning}, \texttt{notice}, \texttt{question}, and
\texttt{summary}.
+The box is defined by begin and end tags such as \texttt{!bnotice} and
\texttt{!enotice}.
The title of the box is fully customizable.
Here are a few examples:
@@ -3954,9 +3946,9 @@
Here~is~a~warning!\\
!ewarning\\
~\\
-!bhint\\
+!bnotice~Hint\\
This~is~a~hint.\\
-!ehint\\
+!enotice\\
~\\
!bblock~This~is~a~block.\\
A~block~has~never~any~icon.\\
@@ -3984,8 +3976,8 @@
Here is a warning!
}
-\DUadmonition[hint]{
-\DUtitle[hint]{Hint}
+\DUadmonition[admonition-hint]{
+\DUtitle[admonition-hint]{Hint}
This is a hint.
}
@@ -4557,7 +4549,9 @@
% font sizes are compatible
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
%
\begin{quote}{\ttfamily \raggedright \noindent
Terminal>~doconce~format~html~myslides~\textbackslash{}\\
@@ -4599,6 +4593,23 @@
\label{latex-beamer-slides}%
}
+Not yet written...
+
+
+%___________________________________________________________________________
+
+\subsubsection*{\phantomsection%
+ Themes%
+ \addcontentsline{toc}{subsubsection}{Themes}%
+ \label{themes}%
+}
+
+Four themes come with Doconce: \texttt{X\_Y}, where \texttt{X} is
\texttt{blue} or \texttt{red}
+(the main color of the slides) and \texttt{Y} is
\href{http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf}{plain}
+for simple layout and
+\href{http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf}{shadow}
+for shadowed boxes and more visual structure in the slides.
+
%___________________________________________________________________________
@@ -4612,7 +4623,7 @@
\DUtitle[system-message]{system-message}
-{\color{red}WARNING/2} in \texttt{manual.rst}, line~3501
+{\color{red}WARNING/2} in \texttt{manual.rst}, line~3513
\hyperlink{id15}{
Duplicate explicit target name: ``mako''.
@@ -4625,6 +4636,17 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+\DUadmonition[warning]{
+\DUtitle[warning]{Warning}
+
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like \texttt{\$\{var\}} to
extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., \texttt{\$\{\textbackslash{}cal
O\}(\textbackslash{}Delta x\textasciicircum{}2)\$} which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+}
+
%___________________________________________________________________________
@@ -4843,6 +4865,22 @@
\addcontentsline{toc}{subsection}{General Problems}%
\label{general-problems}%
}
+
+
+%___________________________________________________________________________
+
+\subsubsection*{\phantomsection%
+ Spellcheck reports a lot of mistakes related LaTeX math%
+ \addcontentsline{toc}{subsubsection}{Spellcheck reports a lot of
mistakes related LaTeX math}%
+ \label{spellcheck-reports-a-lot-of-mistakes-related-latex-math}%
+}
+
+The \texttt{doconce spellcheck} command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant \texttt{tmp\_missing\_*} file and search for the math expressions
that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
%___________________________________________________________________________
@@ -4896,6 +4934,33 @@
\end{itemize}
\end{quote}
+
+
+%___________________________________________________________________________
+
+\subsubsection*{\phantomsection%
+ The Mako preprocessor claims a variable is undefined%
+ \addcontentsline{toc}{subsubsection}{The Mako preprocessor claims a
variable is undefined}%
+ \label{the-mako-preprocessor-claims-a-variable-is-undefined}%
+}
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, \{cal O\}(Delta x\textasciicircum{}2) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use \texttt{\$\{} anywhere in LaTeX
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is \texttt{\$\{\}\textasciicircum{}+\$} type of
indication of superscripts.
+A suggested rewrite is
\texttt{\$\textbackslash{},\{\}\textasciicircum{}+\$}.
+
+The error message will ask you to rerun \texttt{doconce} with
+\texttt{-{}-mako\_strict\_undefined}, which will display the variable that
+is confusing Mako. However, do not continue to use
+\texttt{-{}-mako\_strict\_undefined} while you are debugging because this
+variable will then always be undefined in that mode.
+Use \texttt{\# \#ifdef} directives to comment out large portions of
+the text and apply a ``bisection'' procedure to locate where
+the Mako problem is (without \texttt{-{}-mako\_strict\_undefined}).
%___________________________________________________________________________
@@ -5620,6 +5685,30 @@
\addcontentsline{toc}{subsection}{Problems with HTML Output}%
\label{problems-with-html-output}%
}
+
+
+%___________________________________________________________________________
+
+\subsubsection*{\phantomsection%
+ MathJax formulas are not properly rendered%
+ \addcontentsline{toc}{subsubsection}{MathJax formulas are not properly
rendered}%
+ \label{mathjax-formulas-are-not-properly-rendered}%
+}
+
+Here are some common problems:
+%
+\begin{quote}
+%
+\begin{itemize}
+
+\item Two equations cannot have identical label (this error often arises
+from copying and pasting equations)
+
+\item \texttt{{[}} and \texttt{{]}} brackets must sometimes be replaced by
\texttt{\textbackslash{}lbrack} and \texttt{\textbackslash{}rbrack}
+
+\end{itemize}
+
+\end{quote}
%___________________________________________________________________________
=======================================
--- /doc/demos/manual/manual.sphinx.rst Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.sphinx.rst Fri Jun 28 09:22:02 2013
@@ -5,7 +5,7 @@
===================
:Author: Hans Petter Langtangen
-:Date: May 29, 2013
+:Date: Jun 28, 2013
.. lines beginning with # are doconce comment lines
@@ -658,7 +658,7 @@
=============================
Transformation of a Doconce document ``mydoc.do.txt`` to various other
-formats applies the script ``doconce format``:
+formats apply the script ``doconce format``:
.. code-block:: console
@@ -2348,7 +2348,7 @@
(the label appears in the figure caption in the source code of this
document).
Additional references to the sections :ref:`mathtext`
and :ref:`newcommands` are
nice to demonstrate, as well as a reference to equations,
-say :eq:`myeq1`-:eq:`myeq2`. A comparison of the output and
+say (:ref:`myeq1`)-(:ref:`myeq2`). A comparison of the output and
the source of this document illustrates how labels and references
are handled by the format in question.
@@ -2500,7 +2500,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with ``===`` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in ``html`` output such that search engines can make use of the them.
Bibliography (2)
-----------------
@@ -2696,6 +2700,22 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes ``|`` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+
+.. code-block:: text
+
+
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+
+
Note that not all formats offer alignment of heading or entries
in tables (``rst`` and ``sphinx`` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2708,6 +2728,40 @@
where ``X`` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the ``doconce csv2table`` utility:
+
+
+.. code-block:: console
+
+ Terminal> doconce csv2table somefile.csv > table.do.txt
+
+This is a quick way of writing tables. For example, we can
+write a text file ``tmp.csv`` with
+
+
+.. code-block:: python
+
+ time, velocity, acceleration
+ 0.0, 1.4186, -5.01
+ 2.0, 1.376512, 11.919
+ 4.0, 1.1E+1, 14.717624
+
+Running ``doconce csv2table tmp.csv`` creates the table
+
+
+.. code-block:: text
+
+
+ |------c--------------c--------------c-------|
+ | time | velocity | acceleration |
+ |------c--------------c--------------c-------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------------------|
+
+
Exercises, Problems, Projects, and Examples
-------------------------------------------
@@ -3160,23 +3214,6 @@
\end{align}
!et
-Here is the result:
-
-
-.. math::
- :label: myeq1
-
- {\partial u\over\partial t} = \nabla^2 u + f,
-
-
-
-
-.. math::
- :label: myeq2
-
- {\partial v\over\partial t} = \nabla\cdot(q(u)\nabla v) + g.
-
-
The support of LaTeX mathematics varies among the formats:
@@ -3281,70 +3318,21 @@
newcommands in the ``newcommands*.tex`` files *must* appear on a single
line (multi-line newcommands are too hard to parse with regular
expressions).
-
-*Example.* Suppose we have the following commands in
-``newcommand_replace.tex``:
-
-
-.. code-block:: text
-
-
- \newcommand{\beqa}{\begin{eqnarray}}
- \newcommand{\eeqa}{\end{eqnarray}}
- \newcommand{\ep}{\thinspace . }
- \newcommand{\uvec}{\vec u}
- \newcommand{\Q}{\pmb{Q}}
-
-
-and these in ``newcommands_keep.tex``:
-
-
-.. code-block:: text
-
-
- \newcommand{\x}{\pmb{x}}
- \newcommand{\normalvec}{\pmb{n}}
- \newcommand{\Ddt}[1]{\frac{D#1}{dt}}
- \newcommand{\half}{\frac{1}{2}}
-The LaTeX block
-
-.. code-block:: text
-
-
- \beqa
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{\uvec} &=& \Q \ep label{my:eq2}
- \eeqa
-
-will then be rendered to
-
-.. math::
-
- \pmb{x}\cdot\pmb{n} &= 0, \\
- \frac{D{\vec u}{dt}} &= \pmb{Q} {\thinspace . }
-
-
-in the current format.
-
Admonitions
-----------
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-``block``, ``warning``, ``notice``, ``hint``, ``question``, and
``summary``.
-The box is defined by begin and end tags such as ``!bhint`` and ``!ehint``.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the ``hint`` environment gives a
-box with some admonition icon, text and/or colored background.)
+``block``, ``warning``, ``notice``, ``question``, and ``summary``.
+The box is defined by begin and end tags such as ``!bnotice`` and
``!enotice``.
The title of the box is fully customizable.
Here are a few examples:
@@ -3357,9 +3345,9 @@
Here is a warning!
!ewarning
- !bhint
+ !bnotice Hint
This is a hint.
- !ehint
+ !enotice
!bblock This is a block.
A block has never any icon.
@@ -3383,8 +3371,9 @@
.. warning::
Here is a warning!
+
+.. admonition:: Hint
-.. hint::
This is a hint.
@@ -3686,6 +3675,7 @@
Emacs Doconce Formatter
-----------------------
+
The file `.doconce-mode.el
<https://doconce.googlecode.com/hg/misc/.doconce-mode.el>`_ in the Doconce
source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3787,8 +3777,10 @@
.. font sizes are compatible
+
+Not yet written...
-Text is missing... Just a very preliminary sketch of commands:
+Just a very preliminary sketch of commands:
.. code-block:: console
@@ -3810,6 +3802,17 @@
LaTeX Beamer Slides
-------------------
+Not yet written...
+
+Themes
+~~~~~~
+
+Four themes come with Doconce: ``X_Y``, where ``X`` is ``blue`` or ``red``
+(the main color of the slides) and ``Y`` is `plain
<http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf>`_
+for simple layout and
+`shadow
<http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf>`_
+for shadowed boxes and more visual structure in the slides.
+
Mako Programming
================
@@ -3820,6 +3823,16 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+.. warning::
+ Unfortunately, the combination of Mako and LaTeX mathematics may
+ lead to problems because Mako applies syntax like ``${var}`` to extract
+ variables or call functions, while LaTeX mathematics sometimes applies
+ the same syntax, e.g., ``${\cal O}(\Delta x^2)$`` which looks like a
+ Mako function call. This problem can give rise to strange error
+ messages from Mako, usually that a variable is not defined.
+
+
The Basics of Mako
------------------
@@ -4015,6 +4028,16 @@
General Problems
----------------
+Spellcheck reports a lot of mistakes related LaTeX math
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``doconce spellcheck`` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant ``tmp_missing_*`` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
Doconce aborts because of a syntax error that is not an error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4042,6 +4065,27 @@
* Strings with ``'T<%.1f'`` look as openings of Mako blocks (``<%``);
change
to ``'T < %.1f'`` to avoid this confusion.
+The Mako preprocessor claims a variable is undefined
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, :math:`{\cal O}(\Delta x^2)` is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use ``${`` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is ``${}^+$`` type of indication of superscripts.
+A suggested rewrite is ``$\,{}^+$``.
+
+The error message will ask you to rerun ``doconce`` with
+``--mako_strict_undefined``, which will display the variable that
+is confusing Mako. However, do not continue to use
+``--mako_strict_undefined`` while you are debugging because this
+variable will then always be undefined in that mode.
+Use ``# #ifdef`` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without ``--mako_strict_undefined``).
+
Something goes wrong in the preprocessing step
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4512,6 +4556,16 @@
Problems with HTML Output
-------------------------
+MathJax formulas are not properly rendered
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ * ``[`` and ``]`` brackets must sometimes be replaced by ``\lbrack`` and
``\rbrack``
+
How can I change the layout of the HTML page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================
--- /doc/demos/manual/manual.tex Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.tex Fri Jun 28 09:22:02 2013
@@ -37,10 +37,11 @@
\renewcommand\familydefault{phv}
% Hyperlinks in PDF:
+\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage[%
colorlinks=true,
- linkcolor=blue,
- urlcolor=blue,
+ linkcolor=linkcolor,
+ urlcolor=linkcolor,
citecolor=black,
filecolor=black,
%filecolor=blue,
@@ -75,10 +76,10 @@
% Admonition is an oval gray box
\newmdenv[
- backgroundcolor=gray!10, %% white with 10%% gray
+ backgroundcolor=gray!5, %% white with 5%% gray
skipabove=\topsep,
skipbelow=\topsep,
- outerlinewidth=0.5,
+ outerlinewidth=0,
leftmargin=0,
rightmargin=0,
roundcorner=5,
@@ -145,7 +146,7 @@
\begin{center}
-May 29, 2013
+Jun 28, 2013
\end{center}
\vspace{1cm}
@@ -705,7 +706,7 @@
\label{doconce2formats}
Transformation of a Doconce document \Verb!mydoc.do.txt! to various other
-formats applies the script \Verb!doconce format!:
+formats apply the script \Verb!doconce format!:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
Terminal> doconce format format mydoc.do.txt
\end{Verbatim}
@@ -892,6 +893,7 @@
code with MathJax
scripts so there is no support for mathematics in the discussion forum.
\end{graybox1admon}
+
\begin{graybox1admon}[Notice.]
Figure files must be uploaded to some web site and the filenames name must
be replaced by the relevant URL. This can be automatically edited:
@@ -908,6 +910,7 @@
# Paste mydoc2.html into a new blog page
\end{Verbatim}
\end{graybox1admon}
+
Blog posts at Google can also be published
\href{{http://support.google.com/blogger/bin/answer.py?hl=en&answer=41452}}{automatically
through email}.
A Python program can send the contents of the HTML file
to the blog's email address using the packages \Verb!smtplib! and
\Verb!email!.
@@ -1986,6 +1989,7 @@
becomes correct (sometimes a trial and error process - sticking to
very simple formatting usually avoids such problems).
\end{graybox1admon}
+
\paragraph{Links to Web Addresses.}
Web addresses with links are typeset as
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
@@ -2304,7 +2308,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-{\LaTeX} is the output format).
+{\LaTeX} is the output format). For paragraphs with \Verb!===! heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in \Verb!html! output such that search engines can make use of the
them.
\subsection{Bibliography}
@@ -2345,6 +2353,7 @@
curly braces. You may need to edit your \textsc{Bib}\negthinspace{\TeX}
files to meet this
demand.
\end{graybox1admon}
+
The utility \Verb!doconce fix_bibtex4publish file.bib! fixes several known
issues with \textsc{Bib}\negthinspace{\TeX} files such that Publish has a
better chance of
accepting the entries. Run this utility first, then run Publish,
@@ -2469,6 +2478,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes \Verb!|! can also be inserted to indicate
vertical rules in {\LaTeX} tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+\end{Verbatim}
+
Note that not all formats offer alignment of heading or entries
in tables (\Verb!rst! and \Verb!sphinx! are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2480,6 +2502,33 @@
makes Doconce dump each table to CSV format in a file \Verb!table_X.csv!,
where \Verb!X! is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+
+Data in CSV format can be transformed to Doconce table format
+by the \Verb!doconce csv2table! utility:
+
+\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
+Terminal> doconce csv2table somefile.csv > table.do.txt
+\end{Verbatim}
+This is a quick way of writing tables. For example, we can
+write a text file \Verb!tmp.csv! with
+
+\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+\end{Verbatim}
+Running \Verb!doconce csv2table tmp.csv! creates the table
+
+\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+\end{Verbatim}
\subsection{Exercises, Problems, Projects, and Examples}
@@ -2882,12 +2931,6 @@
\end{align}
!et
\end{Verbatim}
-Here is the result:
-
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, \label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. \label{myeq2}
-\end{align}
The support of {\LaTeX} mathematics varies among the formats:
@@ -2991,57 +3034,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-\paragraph{Example.}
-Suppose we have the following commands in
-\Verb!newcommand_replace.tex!:
-
-\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-\end{Verbatim}
-
-and these in \Verb!newcommands_keep.tex!:
-
-\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-\end{Verbatim}
-
-The {\LaTeX} block
-\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-\end{Verbatim}
-will then be rendered to
-\beqa
-\x\cdot\normalvec &=& 0, \label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep \label{my:eq2}
-\eeqa
-in the current format.
\subsection{Admonitions}
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-\Verb!block!, \Verb!warning!, \Verb!notice!, \Verb!hint!, \Verb!question!,
and \Verb!summary!.
-The box is defined by begin and end tags such as \Verb!!bhint! and
\Verb!!ehint!.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading \emph{Hint} (with number)
-appears, while outside exercises the \Verb!hint! environment gives a
-box with some admonition icon, text and/or colored background.)
+\Verb!block!, \Verb!warning!, \Verb!notice!, \Verb!question!, and
\Verb!summary!.
+The box is defined by begin and end tags such as \Verb!!bnotice! and
\Verb!!enotice!.
The title of the box is fully customizable.
Here are a few examples:
@@ -3051,9 +3056,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3077,17 +3082,21 @@
\begin{graybox1admon}[Warning.]
Here is a warning!
\end{graybox1admon}
+
\begin{graybox1admon}[Hint.]
This is a hint.
\end{graybox1admon}
+
\begin{graybox1admon}[This is a block.]
A block has never any icon.
\end{graybox1admon}
+
\begin{graybox1admon}[Going deeper.]
This is text meant to provide more details. The box has the
layout of the notice box, but a custom title, here "Going deeper".
\end{graybox1admon}
+
Finally some summary:
@@ -3095,6 +3104,7 @@
The main message is to utilize the admonition styles for
marking different parts of the text
\end{graybox1admon}
+
The layout of admonitions depend on the format.
In \Verb!rst! and \Verb!sphinx! one applies the native admonitions, but
in \Verb!sphinx! the \Verb!automake_sphinx.py! script manipulates the HTML
@@ -3365,6 +3375,7 @@
\subsection{Emacs Doconce Formatter}
\label{emacs:doconce}
+
The file
\href{{https://doconce.googlecode.com/hg/misc/.doconce-mode.el}}{.doconce-mode.el}
in the Doconce source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3470,7 +3481,9 @@
% doconce-adjusted styles: easy to switch between styles since
% font sizes are compatible
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3489,6 +3502,15 @@
\noindent
\subsection{{\LaTeX} Beamer Slides}
+
+Not yet written...
+
+\paragraph{Themes.}
+Four themes come with Doconce: \Verb!X_Y!, where \Verb!X! is \Verb!blue!
or \Verb!red!
+(the main color of the slides) and \Verb!Y! is
\href{{http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf}}{\nolinkurl{plain}}
+for simple layout and
+\href{{http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf}}{\nolinkurl{shadow}}
+for shadowed boxes and more visual structure in the slides.
\section{Mako Programming}
@@ -3498,6 +3520,16 @@
sufficient for if-else tests to steer which parts of the text that
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+
+\begin{graybox1admon}[Warning.]
+Unfortunately, the combination of Mako and {\LaTeX} mathematics may
+lead to problems because Mako applies syntax like \Verb!${var}! to extract
+variables or call functions, while {\LaTeX} mathematics sometimes applies
+the same syntax, e.g., \Verb!${\cal O}(\Delta x^2)$! which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+\end{graybox1admon}
\subsection{The Basics of Mako}
@@ -3673,6 +3705,14 @@
\subsection{General Problems}
+
+\paragraph{Spellcheck reports a lot of mistakes related {\LaTeX} math.}
+The \Verb!doconce spellcheck! command should ignore {\LaTeX} math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant \Verb!tmp_missing_*! file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
\paragraph{Doconce aborts because of a syntax error that is not an error.}
Doconce searches for typical syntax errors and usually aborts the
@@ -3698,6 +3738,25 @@
\end{itemize}
\noindent
+\paragraph{The Mako preprocessor claims a variable is undefined.}
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired {\LaTeX} syntax.
+For example, ${\cal O}(\Delta x^2)$ is valid {\LaTeX}, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use \Verb!${! anywhere in {\LaTeX}
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is \Verb!${}^+$! type of indication of superscripts.
+A suggested rewrite is \Verb!$\,{}^+$!.
+
+The error message will ask you to rerun \Verb!doconce! with
+\Verb!--mako_strict_undefined!, which will display the variable that
+is confusing Mako. However, do not continue to use
+\Verb!--mako_strict_undefined! while you are debugging because this
+variable will then always be undefined in that mode.
+Use \Verb!# #ifdef! directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without \Verb!--mako_strict_undefined!).
+
\paragraph{Something goes wrong in the preprocessing step.}
You can examine \Verb!tmp_preprocess__filename! and
\Verb!tmp_mako__filename!,
where \Verb!filename! is the complete name of the Doconce file, to see
@@ -3930,7 +3989,7 @@
When this package is included, \Verb!latex! or \Verb!pdflatex! runs the
\Verb!pygmentize! program and the \Verb!shell-escape! option is required.
-\paragraph{Why are the {\LaTeX} section headings smaller than normal?.}
+\paragraph{Why are the {\LaTeX} section headings smaller than normal?}
Doconce inserts a special command to make the headings
more compact:
@@ -3949,7 +4008,7 @@
by replacing \Verb![compact]! by \Verb![compact,small]! as parameter
specification
for \Verb!titlesec!.
-\paragraph{Can I have {\LaTeX} figures with shadows?.}
+\paragraph{Can I have {\LaTeX} figures with shadows?}
This is easy by including the \Verb!fancybox! and \Verb!graphicx! packages
and wrapping all \Verb!\includegraphics! in a shadow box:
@@ -3961,7 +4020,7 @@
'\\shadowbox{\g<1>}' mydoc.p.tex
\end{Verbatim}
-\paragraph{How can I use my fancy {\LaTeX} environments?.}
+\paragraph{How can I use my fancy {\LaTeX} environments?}
See Section~\ref{manual:theorem:envir} for how to make a custom
theorem environment also in Doconce, without using implementations
restricted to {\LaTeX}.
@@ -4049,7 +4108,18 @@
\subsection{Problems with HTML Output}
-\paragraph{How can I change the layout of the HTML page?.}
+\paragraph{MathJax formulas are not properly rendered.}
+Here are some common problems:
+
+\begin{itemize}
+ \item Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ \item \Verb![! and \Verb!]! brackets must sometimes be replaced by
\Verb!\lbrack! and \Verb!\rbrack!
+\end{itemize}
+
+\noindent
+\paragraph{How can I change the layout of the HTML page?}
The easiest way is to edit the HTML style or the HTML code directly.
However, those edits are overwritten the next time you compile the
Doconce document to HTML. The edits should therefore be automated
@@ -4086,7 +4156,7 @@
use the \Verb!sphinx! format and one its many themes.
-\paragraph{Why do figures look ugly when using HTML templates?.}
+\paragraph{Why do figures look ugly when using HTML templates?}
The HTML header that Doconce generates contain special styles for
figure captions and the horizontal rule above figures. When using
templates these styles are not defined, resulting in a rule that
=======================================
--- /doc/demos/manual/manual.txt Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.txt Fri Jun 28 09:22:02 2013
@@ -6,7 +6,7 @@
[1] Center for Biomedical Computing, Simula Research Laboratory
[2] Department of Informatics, University of Oslo
-Date: May 29, 2013
+Date: Jun 28, 2013
What Is Doconce?
================
@@ -565,7 +565,7 @@
=============================
Transformation of a Doconce document mydoc.do.txt to various other
-formats applies the script doconce format::
+formats apply the script doconce format::
Terminal> doconce format format mydoc.do.txt
@@ -2166,7 +2166,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with === heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in html output such that search engines can make use of the them.
Bibliography
------------
@@ -2343,6 +2347,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes | can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like::
+
+
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+
+
Note that not all formats offer alignment of heading or entries
in tables (rst and sphinx are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2355,6 +2372,33 @@
where X is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the doconce csv2table utility::
+
+
+ Terminal> doconce csv2table somefile.csv > table.do.txt
+
+This is a quick way of writing tables. For example, we can
+write a text file tmp.csv with::
+
+
+ time, velocity, acceleration
+ 0.0, 1.4186, -5.01
+ 2.0, 1.376512, 11.919
+ 4.0, 1.1E+1, 14.717624
+
+Running doconce csv2table tmp.csv creates the table::
+
+
+ |------c--------------c--------------c-------|
+ | time | velocity | acceleration |
+ |------c--------------c--------------c-------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------------------|
+
+
Exercises, Problems, Projects, and Examples
-------------------------------------------
@@ -2758,13 +2802,6 @@
\end{align}
!et
-Here is the result::
-
- \begin{align}
- {\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
- {\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
- \end{align}
-
The support of LaTeX mathematics varies among the formats:
@@ -2865,60 +2902,20 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-*Example.* Suppose we have the following commands in
-newcommand_replace.tex::
-
-
- \newcommand{\beqa}{\begin{eqnarray}}
- \newcommand{\eeqa}{\end{eqnarray}}
- \newcommand{\ep}{\thinspace . }
- \newcommand{\uvec}{\vec u}
- \newcommand{\Q}{\pmb{Q}}
-
-
-and these in newcommands_keep.tex::
-
-
- \newcommand{\x}{\pmb{x}}
- \newcommand{\normalvec}{\pmb{n}}
- \newcommand{\Ddt}[1]{\frac{D#1}{dt}}
- \newcommand{\half}{\frac{1}{2}}
-
-
-The LaTeX block::
-
-
- \beqa
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{\uvec} &=& \Q \ep label{my:eq2}
- \eeqa
-
-will then be rendered to::
-
- \begin{eqnarray}
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
- \end{eqnarray}
-
-in the current format.
Admonitions
-----------
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-block, warning, notice, hint, question, and summary.
-The box is defined by begin and end tags such as !bhint and !ehint.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the hint environment gives a
-box with some admonition icon, text and/or colored background.)
+block, warning, notice, question, and summary.
+The box is defined by begin and end tags such as !bnotice and !enotice.
The title of the box is fully customizable.
Here are a few examples::
@@ -2928,9 +2925,9 @@
Here is a warning!
!ewarning
- !bhint
+ !bnotice Hint
This is a hint.
- !ehint
+ !enotice
!bblock This is a block.
A block has never any icon.
@@ -3332,7 +3329,9 @@
------------
-Text is missing... Just a very preliminary sketch of commands::
+Not yet written...
+
+Just a very preliminary sketch of commands::
Terminal> doconce format html myslides \
@@ -3353,6 +3352,17 @@
LaTeX Beamer Slides
-------------------
+Not yet written...
+
+Themes
+~~~~~~
+
+Four themes come with Doconce: X_Y, where X is blue or red
+(the main color of the slides) and Y is plain
(http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf)
+for simple layout and
+shadow (http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf)
+for shadowed boxes and more visual structure in the slides.
+
Mako Programming
================
@@ -3363,6 +3373,14 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+*Warning.*
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like ${var} to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., ${\cal O}(\Delta x^2)$ which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+
The Basics of Mako
------------------
@@ -3545,6 +3563,16 @@
General Problems
----------------
+Spellcheck reports a lot of mistakes related LaTeX math
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The doconce spellcheck command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant tmp_missing_* file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
Doconce aborts because of a syntax error that is not an error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3572,6 +3600,27 @@
* Strings with 'T<%.1f' look as openings of Mako blocks (<%); change
to 'T < %.1f' to avoid this confusion.
+The Mako preprocessor claims a variable is undefined
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, {\cal O}(\Delta x^2) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use ${ anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is ${}^+$ type of indication of superscripts.
+A suggested rewrite is $\,{}^+$.
+
+The error message will ask you to rerun doconce with
+--mako_strict_undefined, which will display the variable that
+is confusing Mako. However, do not continue to use
+--mako_strict_undefined while you are debugging because this
+variable will then always be undefined in that mode.
+Use # #ifdef directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without --mako_strict_undefined).
+
Something goes wrong in the preprocessing step
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4009,6 +4058,16 @@
Problems with HTML Output
-------------------------
+MathJax formulas are not properly rendered
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ * [ and ] brackets must sometimes be replaced by \lbrack and \rbrack
+
How can I change the layout of the HTML page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================
--- /doc/demos/manual/manual.xml Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.xml Fri Jun 28 09:22:02 2013
@@ -2,7 +2,7 @@
<!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils
Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">
<!-- Generated by Docutils 0.9 -->
<document source="manual.rst"><comment xml:space="preserve">Automatically
generated reST file from Doconce source
-(http://code.google.com/p/doconce/)</comment><section
ids="doconce-description" names="doconce\ description"><title>Doconce
Description</title><field_list><field><field_name>Author</field_name><field_body><paragraph>Hans
Petter
Langtangen</paragraph></field_body></field><field><field_name>Date</field_name><field_body><paragraph>May
29, 2013</paragraph></field_body></field></field_list><comment
xml:space="preserve">lines beginning with # are doconce comment
lines</comment><comment xml:space="preserve">(documents can also have mako
comment lines)</comment><target refid="what-is-doconce"/></section><section
ids="id1 what-is-doconce" names="what\ is\ doconce?
what:is:doconce"><title>What Is Doconce?</title><paragraph>Doconce is a
very simple and minimally tagged markup language that
+(http://code.google.com/p/doconce/)</comment><section
ids="doconce-description" names="doconce\ description"><title>Doconce
Description</title><field_list><field><field_name>Author</field_name><field_body><paragraph>Hans
Petter
Langtangen</paragraph></field_body></field><field><field_name>Date</field_name><field_body><paragraph>Jun
28, 2013</paragraph></field_body></field></field_list><comment
xml:space="preserve">lines beginning with # are doconce comment
lines</comment><comment xml:space="preserve">(documents can also have mako
comment lines)</comment><target refid="what-is-doconce"/></section><section
ids="id1 what-is-doconce" names="what\ is\ doconce?
what:is:doconce"><title>What Is Doconce?</title><paragraph>Doconce is a
very simple and minimally tagged markup language that
looks like ordinary ASCII text, much like what you would use in an
email, but the text can be transformed to numerous other formats,
including HTML, Sphinx, LaTeX, PDF, reStructuredText (reST), Markdown,
@@ -243,7 +243,7 @@
lot of formats, with a corresponding
<reference name="web demo"
refuri="https://doconce.googlecode.com/hg/doc/demos/tutorial/index.html">web
demo</reference><target ids="web-demo" names="web\ demo"
refuri="https://doconce.googlecode.com/hg/doc/demos/tutorial/index.html"/>
of the results.</paragraph><comment xml:space="preserve">Example on
including another Doconce file:</comment><target
refid="doconce2formats"/></section></section><section
ids="from-doconce-to-other-formats doconce2formats" names="from\ doconce\
to\ other\ formats doconce2formats"><title>From Doconce to Other
Formats</title><paragraph>Transformation of a Doconce document
<literal>mydoc.do.txt</literal> to various other
-formats applies the script <literal>doconce
format</literal>:</paragraph><literal_block
xml:space="preserve">Terminal> doconce format format
mydoc.do.txt</literal_block><paragraph>or just:</paragraph><literal_block
xml:space="preserve">Terminal> doconce format format
mydoc</literal_block><section ids="generating-a-makefile"
names="generating\ a\ makefile"><title>Generating a
makefile</title><paragraph>Producing HTML, Sphinx, and in particular LaTeX
documents from
+formats apply the script <literal>doconce
format</literal>:</paragraph><literal_block
xml:space="preserve">Terminal> doconce format format
mydoc.do.txt</literal_block><paragraph>or just:</paragraph><literal_block
xml:space="preserve">Terminal> doconce format format
mydoc</literal_block><section ids="generating-a-makefile"
names="generating\ a\ makefile"><title>Generating a
makefile</title><paragraph>Producing HTML, Sphinx, and in particular LaTeX
documents from
Doconce sources requires a few commands. Often you want to
produce several different formats. The relevant commands should
then be placed in a script that acts as a
"makefile".</paragraph><paragraph>The <literal>doconce
makefile</literal> can be used to automatically generate
@@ -991,7 +991,9 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).</paragraph></section><section
ids="bibliography-2" names="bibliography\ (2)"><title>Bibliography
(2)</title><paragraph>Doconce applies the software tool <reference
name="Publish"
refuri="https://bitbucket.org/logg/publish">Publish</reference><target
dupnames="publish" ids="id6" refuri="https://bitbucket.org/logg/publish"/>
to handle the bibliography in a
+LaTeX is the output format). For paragraphs with <literal>===</literal>
heading,
+the index keywords should be placed above the
heading.</paragraph><paragraph>The keywords in the index are automatically
placed in a meta
+tag in <literal>html</literal> output such that search engines can make
use of the them.</paragraph></section><section ids="bibliography-2"
names="bibliography\ (2)"><title>Bibliography
(2)</title><paragraph>Doconce applies the software tool <reference
name="Publish"
refuri="https://bitbucket.org/logg/publish">Publish</reference><target
dupnames="publish" ids="id6" refuri="https://bitbucket.org/logg/publish"/>
to handle the bibliography in a
document. With Publish it is easy to import BibTeX data and maintain a
database in a clean, self-explanatory textual format. From the Publish
format it is easy to go BibTeX and reST or straightforward Doconce
@@ -1069,7 +1071,14 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes <literal>|</literal> can also be inserted to
indicate
vertical rules in LaTeX tables (they are ignored for other formats).
-Note that not all formats offer alignment of heading or entries
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks
like:</paragraph><literal_block xml:space="preserve">|
--c--------c-----------c--------|
+|time | velocity | acceleration |
+|--l--------r-----------r--------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------|</literal_block><paragraph>Note that not
all formats offer alignment of heading or entries
in tables (<literal>rst</literal> and <literal>sphinx</literal> are
examples). Also note that
Doconce tables are very simple: neither entries nor
headings can span several columns or rows. When that functionality
@@ -1077,7 +1086,18 @@
the format and insert format-specific code for
tables.</paragraph><paragraph>The command-line option
<literal>--tables2csv</literal> (to <literal>doconce format</literal>)
makes Doconce dump each table to CSV format in a file
<literal>table_X.csv</literal>,
where <literal>X</literal> is the table number. This feature makes it easy
to
-load tables into spreadsheet programs for further
analysis.</paragraph></section><section
ids="exercises-problems-projects-and-examples" names="exercises,\
problems,\ projects,\ and\ examples"><title>Exercises, Problems, Projects,
and Examples</title><paragraph>Doconce has special support for four types
of "exercises", named
+load tables into spreadsheet programs for further
analysis.</paragraph><paragraph>Data in CSV format can be transformed to
Doconce table format
+by the <literal>doconce csv2table</literal>
utility:</paragraph><literal_block xml:space="preserve">Terminal>
doconce csv2table somefile.csv >
table.do.txt</literal_block><paragraph>This is a quick way of writing
tables. For example, we can
+write a text file <literal>tmp.csv</literal>
with:</paragraph><literal_block xml:space="preserve">time, velocity,
acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624</literal_block><paragraph>Running <literal>doconce
csv2table tmp.csv</literal> creates the table:</paragraph><literal_block
xml:space="preserve">|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
</literal_block></section><section
ids="exercises-problems-projects-and-examples" names="exercises,\
problems,\ projects,\ and\ examples"><title>Exercises, Problems, Projects,
and Examples</title><paragraph>Doconce has special support for four types
of "exercises", named
<emphasis>exercise</emphasis>, <emphasis>problem</emphasis>,
<emphasis>project</emphasis>, or <emphasis>example</emphasis>.
These are all typeset as special kind of
sections. Such sections start with a subsection
@@ -1355,10 +1375,7 @@
{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
\end{align}
-!et</literal_block><paragraph>Here is the
result:</paragraph><literal_block xml:space="preserve">\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
-\end{align}</literal_block><paragraph>The support of LaTeX mathematics
varies among the formats:</paragraph><block_quote><bullet_list
bullet="*"><list_item><paragraph>Output in LaTeX (<literal>latex</literal>
and <literal>pdflatex</literal> formats) has of course full
+!et</literal_block><paragraph>The support of LaTeX mathematics varies
among the formats:</paragraph><block_quote><bullet_list
bullet="*"><list_item><paragraph>Output in LaTeX (<literal>latex</literal>
and <literal>pdflatex</literal> formats) has of course full
support of all LaTeX mathematics, of
course.</paragraph></list_item><list_item><paragraph>The
<literal>html</literal> format supports single equations and multiple
equations
via the align environment, also with
labels.</paragraph></list_item><list_item><paragraph>Markdown
(<literal>pandoc</literal> format) allows single equations and inline
mathematics.</paragraph></list_item><list_item><paragraph>MediaWiki
(<literal>mwiki</literal> format) does not enable labels in equations and
hence
equations cannot be referred
to.</paragraph></list_item></bullet_list></block_quote><paragraph>The main
conclusion is that for
@@ -1414,39 +1431,21 @@
<literal>newcommands_replace.tex</literal> and expanded by Doconce. The
definitions of
newcommands in the <literal>newcommands*.tex</literal> files
<emphasis>must</emphasis> appear on a single
line (multi-line newcommands are too hard to parse with regular
-expressions).</paragraph><paragraph><emphasis>Example.</emphasis> Suppose
we have the following commands in
-<literal>newcommand_replace.tex</literal>:</paragraph><literal_block
xml:space="preserve">\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}</literal_block><paragraph>and these in
<literal>newcommands_keep.tex</literal>:</paragraph><literal_block
xml:space="preserve">\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}</literal_block><paragraph>The LaTeX
block:</paragraph><literal_block xml:space="preserve">\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa</literal_block><paragraph>will then be rendered
to:</paragraph><literal_block xml:space="preserve">\begin{eqnarray}
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
-\end{eqnarray}</literal_block><paragraph>in the current
format.</paragraph></section><section ids="admonitions"
names="admonitions"><title>Admonitions</title><paragraph>Doconce offers
strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+expressions).</paragraph></section><section ids="admonitions"
names="admonitions"><title>Admonitions</title><paragraph>Doconce offers
strong support for admonition environments, such
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.</paragraph><paragraph>The following admonition environments
are available:
-<literal>block</literal>, <literal>warning</literal>,
<literal>notice</literal>, <literal>hint</literal>,
<literal>question</literal>, and <literal>summary</literal>.
-The box is defined by begin and end tags such as <literal>!bhint</literal>
and <literal>!ehint</literal>.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading <emphasis>Hint</emphasis>
(with number)
-appears, while outside exercises the <literal>hint</literal> environment
gives a
-box with some admonition icon, text and/or colored background.)
+<literal>block</literal>, <literal>warning</literal>,
<literal>notice</literal>, <literal>question</literal>, and
<literal>summary</literal>.
+The box is defined by begin and end tags such as
<literal>!bnotice</literal> and <literal>!enotice</literal>.
The title of the box is fully customizable.</paragraph><paragraph>Here are
a few examples:</paragraph><literal_block xml:space="preserve">!bwarning
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -1462,7 +1461,7 @@
!bsummary
The main message is to utilize the admonition styles for
marking different parts of the text
-!esummary</literal_block><paragraph>The above Doconce code is in the
present format rendered as</paragraph><warning><paragraph>Here is a
warning!</paragraph></warning><hint><paragraph>This is a
hint.</paragraph></hint><admonition
classes="admonition-this-is-a-block"><title>This is a
block</title><paragraph>A block has never any
icon.</paragraph></admonition><admonition
classes="admonition-going-deeper"><title>Going
deeper</title><paragraph>This is text meant to provide more details. The
box has the
+!esummary</literal_block><paragraph>The above Doconce code is in the
present format rendered as</paragraph><warning><paragraph>Here is a
warning!</paragraph></warning><admonition
classes="admonition-hint"><title>Hint</title><paragraph>This is a
hint.</paragraph></admonition><admonition
classes="admonition-this-is-a-block"><title>This is a
block</title><paragraph>A block has never any
icon.</paragraph></admonition><admonition
classes="admonition-going-deeper"><title>Going
deeper</title><paragraph>This is text meant to provide more details. The
box has the
layout of the notice box, but a custom title, here "Going
deeper".</paragraph></admonition><paragraph>Finally some
summary:</paragraph><admonition
classes="admonition-summary"><title>Summary</title><paragraph>The main
message is to utilize the admonition styles for
marking different parts of the text</paragraph></admonition><paragraph>The
layout of admonitions depend on the format.
In <literal>rst</literal> and <literal>sphinx</literal> one applies the
native admonitions, but
@@ -1641,17 +1640,26 @@
<literal>frac</literal> parameter for LaTeX Beamer) so they become
effective
on the
slide.</paragraph></list_item></bullet_list></block_quote><paragraph>Doconce
can generate two types of slides: HTML5+CSS3 type of
slides to be presented through a web browser, and classical
-LaTeX Beamer slides.</paragraph></section><section ids="html5-slides"
names="html5\ slides"><title>HTML5 Slides</title><comment
xml:space="preserve">doconce-adjusted styles: easy to switch between styles
since</comment><comment xml:space="preserve">font sizes are
compatible</comment><paragraph>Text is missing... Just a very preliminary
sketch of commands:</paragraph><literal_block
xml:space="preserve">Terminal> doconce format html myslides \
+LaTeX Beamer slides.</paragraph></section><section ids="html5-slides"
names="html5\ slides"><title>HTML5 Slides</title><comment
xml:space="preserve">doconce-adjusted styles: easy to switch between styles
since</comment><comment xml:space="preserve">font sizes are
compatible</comment><paragraph>Not yet
written...</paragraph><paragraph>Just a very preliminary sketch of
commands:</paragraph><literal_block xml:space="preserve">Terminal>
doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
Terminal> doconce slides_html myslides reveal \
--html_slide_theme=darkgray</literal_block><section
ids="potential-problems" names="potential\ problems"><title>Potential
Problems</title><block_quote><bullet_list
bullet="*"><list_item><paragraph>Some newer Firefox does not show rounded
corners of the
admonition boxes, e.g., notice and warning (tested on
Ubuntu)</paragraph></list_item><list_item><paragraph>Doconce performs some
adjustments of the spacing around
-equations. More edits (automate with <literal>doconce subst</literal>)
might be
needed.</paragraph></list_item></bullet_list></block_quote></section></section><section
ids="latex-beamer-slides" names="latex\ beamer\ slides"><title>LaTeX Beamer
Slides</title></section></section><section ids="mako-programming"
names="mako\ programming"><title>Mako Programming</title><system_message
backrefs="id15" level="2" line="3501" source="manual.rst"
type="WARNING"><paragraph>Duplicate explicit target name:
"mako".</paragraph></system_message><paragraph>The <reference
name="Mako" refuri="http://docs.makotemplates.org/">Mako</reference><target
dupnames="mako" ids="id15" refuri="http://docs.makotemplates.org/"/>
templating engine is used
+equations. More edits (automate with <literal>doconce subst</literal>)
might be
needed.</paragraph></list_item></bullet_list></block_quote></section></section><section
ids="latex-beamer-slides" names="latex\ beamer\ slides"><title>LaTeX Beamer
Slides</title><paragraph>Not yet written...</paragraph><section
ids="themes" names="themes"><title>Themes</title><paragraph>Four themes
come with Doconce: <literal>X_Y</literal>, where <literal>X</literal> is
<literal>blue</literal> or <literal>red</literal>
+(the main color of the slides) and <literal>Y</literal> is <reference
name="plain"
refuri="http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf">plain</reference><target
ids="plain" names="plain"
refuri="http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf"/>
+for simple layout and
+<reference name="shadow"
refuri="http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf">shadow</reference><target
ids="shadow" names="shadow"
refuri="http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf"/>
+for shadowed boxes and more visual structure in the
slides.</paragraph></section></section></section><section
ids="mako-programming" names="mako\ programming"><title>Mako
Programming</title><system_message backrefs="id15" level="2" line="3513"
source="manual.rst" type="WARNING"><paragraph>Duplicate explicit target
name: "mako".</paragraph></system_message><paragraph>The
<reference name="Mako"
refuri="http://docs.makotemplates.org/">Mako</reference><target
dupnames="mako" ids="id15" refuri="http://docs.makotemplates.org/"/>
templating engine is used
as preprocessor for Doconce documents, but the <reference
name="Preprocess"
refuri="http://code.google.com/p/preprocess">Preprocess</reference><target
dupnames="preprocess" ids="id16"
refuri="http://code.google.com/p/preprocess"/> is run prior to Mako and is
recommended for
including other files via <literal># #include
"filename"</literal>. Preprocess is also
sufficient for if-else tests to steer which parts of the text that
are to be compiled. For more demanding tasks, use Mako, which resembles
-a real programming language.</paragraph><section ids="the-basics-of-mako"
names="the\ basics\ of\ mako"><title>The Basics of
Mako</title><paragraph>Just a preliminary sketch of some Mako code (next
example is better!):</paragraph><literal_block xml:space="preserve">#
Define variables
+a real programming language.</paragraph><warning><paragraph>Unfortunately,
the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like
<literal>${var}</literal> to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., <literal>${\cal O}(\Delta x^2)$</literal> which
looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not
defined.</paragraph></warning><section ids="the-basics-of-mako" names="the\
basics\ of\ mako"><title>The Basics of Mako</title><paragraph>Just a
preliminary sketch of some Mako code (next example is
better!):</paragraph><literal_block xml:space="preserve"># Define variables
<%
mycounter = 1
mydict = {}
@@ -1779,7 +1787,12 @@
track down this syntax problem yourself. However, Doconce applies
regular expressions to a large extent for transforming text, and
regular expressions may sometimes fail. Therefore, there is a chance that
legal
-Doconce syntax is not treated properly.</paragraph></section><section
ids="general-problems" names="general\ problems"><title>General
Problems</title><section
ids="doconce-aborts-because-of-a-syntax-error-that-is-not-an-error"
names="doconce\ aborts\ because\ of\ a\ syntax\ error\ that\ is\ not\ an\
error"><title>Doconce aborts because of a syntax error that is not an
error</title><paragraph>Doconce searches for typical syntax errors and
usually aborts the
+Doconce syntax is not treated properly.</paragraph></section><section
ids="general-problems" names="general\ problems"><title>General
Problems</title><section
ids="spellcheck-reports-a-lot-of-mistakes-related-latex-math"
names="spellcheck\ reports\ a\ lot\ of\ mistakes\ related\ latex\
math"><title>Spellcheck reports a lot of mistakes related LaTeX
math</title><paragraph>The <literal>doconce spellcheck</literal> command
should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant <literal>tmp_missing_*</literal> file and search for the math
expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.</paragraph></section><section
ids="doconce-aborts-because-of-a-syntax-error-that-is-not-an-error"
names="doconce\ aborts\ because\ of\ a\ syntax\ error\ that\ is\ not\ an\
error"><title>Doconce aborts because of a syntax error that is not an
error</title><paragraph>Doconce searches for typical syntax errors and
usually aborts the
execution if errors are found. However, it may happen,
especially in verbatim blocks, that Doconce reports syntax errors
that are not errors. To continue execution, simply add the
@@ -1789,7 +1802,21 @@
because it thinks these lines are Mako statements. Doconce detects
this problem and avoids running Mako. Examine the output from
Doconce: warnings are issued if Mako is not
run.</paragraph></section><section
ids="the-mako-preprocessor-is-fooled-by-doconce-text" names="the\ mako\
preprocessor\ is\ fooled\ by\ doconce\ text"><title>The Mako preprocessor
is fooled by Doconce text</title><paragraph>Here are possible problems for
Mako:</paragraph><block_quote><bullet_list
bullet="*"><list_item><paragraph>Strings with
<literal>'T<%.1f'</literal> look as openings of Mako blocks
(<literal><%</literal>); change
-to <literal>'T < %.1f'</literal> to avoid this
confusion.</paragraph></list_item></bullet_list></block_quote></section><section
ids="something-goes-wrong-in-the-preprocessing-step" names="something\
goes\ wrong\ in\ the\ preprocessing\ step"><title>Something goes wrong in
the preprocessing step</title><paragraph>You can examine
<literal>tmp_preprocess__filename</literal> and
<literal>tmp_mako__filename</literal>,
+to <literal>'T < %.1f'</literal> to avoid this
confusion.</paragraph></list_item></bullet_list></block_quote></section><section
ids="the-mako-preprocessor-claims-a-variable-is-undefined" names="the\
mako\ preprocessor\ claims\ a\ variable\ is\ undefined"><title>The Mako
preprocessor claims a variable is undefined</title><paragraph>Very often
such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, {cal O}(Delta x^2) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use <literal>${</literal> anywhere in LaTeX
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is <literal>${}^+$</literal> type of indication of
superscripts.
+A suggested rewrite is
<literal>$\,{}^+$</literal>.</paragraph><paragraph>The error message will
ask you to rerun <literal>doconce</literal> with
+<literal>--mako_strict_undefined</literal>, which will display the
variable that
+is confusing Mako. However, do not continue to use
+<literal>--mako_strict_undefined</literal> while you are debugging because
this
+variable will then always be undefined in that mode.
+Use <literal># #ifdef</literal> directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without
<literal>--mako_strict_undefined</literal>).</paragraph></section><section
ids="something-goes-wrong-in-the-preprocessing-step" names="something\
goes\ wrong\ in\ the\ preprocessing\ step"><title>Something goes wrong in
the preprocessing step</title><paragraph>You can examine
<literal>tmp_preprocess__filename</literal> and
<literal>tmp_mako__filename</literal>,
where <literal>filename</literal> is the complete name of the Doconce
file, to see
what the preprocessors actually to and if something is wrong in these
files before Doconce starts translating the text.
@@ -1935,7 +1962,8 @@
and because of the indentation in the original Doconce text, the gwiki
output looks somewhat ugly. The good thing is that this gwiki source
is seldom to be looked at - it is the Doconce source that one edits
-further.</paragraph></section></section><section
ids="problems-with-html-output" names="problems\ with\ html\
output"><title>Problems with HTML Output</title><section
ids="how-can-i-change-the-layout-of-the-html-page" names="how\ can\ i\
change\ the\ layout\ of\ the\ html\ page?"><title>How can I change the
layout of the HTML page?</title><paragraph>The easiest way is to edit the
HTML style or the HTML code directly.
+further.</paragraph></section></section><section
ids="problems-with-html-output" names="problems\ with\ html\
output"><title>Problems with HTML Output</title><section
ids="mathjax-formulas-are-not-properly-rendered" names="mathjax\ formulas\
are\ not\ properly\ rendered"><title>MathJax formulas are not properly
rendered</title><paragraph>Here are some common
problems:</paragraph><block_quote><bullet_list
bullet="*"><list_item><paragraph>Two equations cannot have identical label
(this error often arises
+from copying and pasting
equations)</paragraph></list_item><list_item><paragraph><literal>[</literal>
and <literal>]</literal> brackets must sometimes be replaced by
<literal>\lbrack</literal> and
<literal>\rbrack</literal></paragraph></list_item></bullet_list></block_quote></section><section
ids="how-can-i-change-the-layout-of-the-html-page" names="how\ can\ i\
change\ the\ layout\ of\ the\ html\ page?"><title>How can I change the
layout of the HTML page?</title><paragraph>The easiest way is to edit the
HTML style or the HTML code directly.
However, those edits are overwritten the next time you compile the
Doconce document to HTML. The edits should therefore be automated
using <literal>doconce subst</literal> (for regular expression editing) or
<literal>doconce replace</literal>
=======================================
--- /doc/demos/manual/manual_pdflatex.pdf Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual_pdflatex.pdf Fri Jun 28 09:22:02 2013
Binary file, no diff available.
=======================================
--- /doc/manual/make.sh Wed Apr 24 00:37:11 2013
+++ /doc/manual/make.sh Fri Jun 28 09:22:02 2013
@@ -31,6 +31,8 @@
# doconce html format:
$d2f html manual.do.txt --no_mako --no_pygments_html
if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi
+# Need a fix: remove newcommands (and math) when displayed on googlecode
+doconce subst -s '<!\-\- newcommands.*?\$\$.*?\$\$' '' manual.html
# Sphinx
$d2f sphinx manual.do.txt --no_mako
@@ -73,8 +75,10 @@
$d2f epytext manual.do.txt --no_mako
if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi
-$d2f st manual.do.txt --no_mako
-if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi
+#Problem with st
+#$d2f st manual.do.txt --no_mako
+#if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi
+
$d2f pandoc manual.do.txt --no_mako
if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi
@@ -120,7 +124,7 @@
rm -rf demo
mkdir demo
-cp -r manual.do.txt manual.html figs manual.p.tex manual.tex manual.pdf
manual_pdflatex.pdf manual.rst manual.sphinx.rst manual.xml manual.rst.html
manual.rst.tex manual.rst.pdf manual.gwiki manual.cwiki manual.mwiki
manual.txt manual.epytext manual.st manual.md sphinx-rootdir/_build/html
demo
+cp -r manual.do.txt manual.html figs manual.p.tex manual.tex manual.pdf
manual_pdflatex.pdf manual.rst manual.sphinx.rst manual.xml manual.rst.html
manual.rst.tex manual.rst.pdf manual.gwiki manual.cwiki manual.mwiki
manual.txt manual.epytext manual.md sphinx-rootdir/_build/html demo
cd demo
cat > index.html <<EOF
@@ -167,7 +171,6 @@
<a href="manual.cwiki">Creole wiki</a>,
<a href="manual.mwiki">MediaWiki</a>,
<a href="manual.md">Markdown</a> (Pandoc extended version),
-<a href="manual.st">Structured Text</a>,
<a href="manual.epytext">Epytext</a>,
and maybe the most important format of all:
<a href="manual.txt">plain untagged ASCII text</a>.
=======================================
--- /doc/manual/manual.do.txt Mon Jun 24 11:00:38 2013
+++ /doc/manual/manual.do.txt Fri Jun 28 09:22:02 2013
@@ -1356,6 +1356,7 @@
\end{align}
|et
!ec
+# #ifdef EXTRA
Here is the result:
!bt
@@ -1364,6 +1365,7 @@
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. label{myeq2}
\end{align}
!et
+# #endif
The support of LaTeX mathematics varies among the formats:
@@ -1456,6 +1458,7 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
+# #ifdef EXTRA
__Example.__ Suppose we have the following commands in
`newcommand_replace.tex`:
@@ -1480,6 +1483,7 @@
\eeqa
!et
in the current format.
+# #endif
===== Admonitions =====
=======================================
--- /lib/doconce/common.py Mon Jun 24 11:00:38 2013
+++ /lib/doconce/common.py Fri Jun 28 09:22:02 2013
@@ -5,7 +5,6 @@
here.
"""
import re, sys, urllib
-from misc import option
# Identifiers in the text used to identify code and math blocks
_CODE_BLOCK = '<<<!!CODE_BLOCK'
@@ -29,6 +28,12 @@
'--- end exercise ---'),
}
+def _abort():
+ if '--no_abort' in sys.argv:
+ print 'avoided abortion because of --no-abort'
+ else:
+ print 'Abort! (add --no_abort on the command line to avoid this
abortion)'
+ sys.exit(1)
def safe_join(lines, delimiter):
try:
@@ -38,10 +43,10 @@
if "'ascii' codec can't decode" in e and 'position' in e:
pos = int(e.split('position')[1].split(':'))
print filestr[pos-50:pos], '[problematic char]',
filestr[pos+1:pos+51]
- sys.exit(1)
+ _abort()
else:
print e
- sys.exit(1)
+ _abort()
def fix_backslashes(text):
"""
@@ -162,7 +167,7 @@
url = url.replace('%', '\\%').replace('#', '\\#')
return url
else:
- print 'BUG'; sys.exit(1)
+ print 'BUG'; _abort()
def align2equations(filestr, format):
"""Turn align environments into separate equation environments."""
@@ -259,7 +264,7 @@
plotfiles = sorted(glob.glob(filename))
if not plotfiles:
print 'No plotfiles on the form', filename
- sys.exit(1)
+ _abort()
basename = os.path.basename(plotfiles[0])
stem, ext = os.path.splitext(basename)
kwargs['casename'] = stem
@@ -328,12 +333,12 @@
print '\n\nTwo', pattern, 'after each other!\n'
for j in range(begin_ends[k-1][1], begin_ends[k][1]+1):
print lines[j]
- sys.exit(1)
+ _abort()
if begin_ends[-1][0].startswith('!b'):
print 'Missing %s after final %s' % \
(begin_ends[-1][0].replace('!b', '!e'),
begin_ends[-1][0])
- sys.exit(1)
+ _abort()
def remove_code_and_tex(filestr):
@@ -393,12 +398,12 @@
if len(code_blocks) != n:
print '*** BUG: found %d code block markers for %d initial code
blocks\nAbort!' % (n, len(code_blocks))
print 'Possible cause: !bc and !ec inside code blocks - replace by
|bc and |ec'
- sys.exit(1)
+ _abort()
n = filestr.count(_MATH_BLOCK)
if len(tex_blocks) != n:
print '*** BUG: found %d tex block markers for %d initial tex
blocks\nAbort!' % (n, len(tex_blocks))
print 'Possible cause: !bt and !et inside code blocks - replace by
|bt and |ec'
- sys.exit(1)
+ _abort()
lines = filestr.splitlines()
=======================================
--- /lib/doconce/cwiki.py Mon Mar 11 00:28:37 2013
+++ /lib/doconce/cwiki.py Fri Jun 28 09:22:02 2013
@@ -5,7 +5,7 @@
# Simple edit of gwiki.py
import re, os, commands, sys
-from common import default_movie, plain_exercise, insert_code_and_tex
+from common import default_movie, plain_exercise, insert_code_and_tex,
_abort
def cwiki_code(filestr, code_blocks, code_block_types,
tex_blocks, format):
@@ -37,7 +37,7 @@
if failure:
print '\n**** Warning: could not run', cmd
print 'Convert %s to PNG format manually' % filename
- sys.exit(1)
+ _abort()
filename = root + '.png'
caption = m.group('caption')
# keep label if it's there:
=======================================
--- /lib/doconce/doconce.py Mon Jun 24 11:00:38 2013
+++ /lib/doconce/doconce.py Fri Jun 28 09:22:02 2013
@@ -7,13 +7,6 @@
# citations is then lost)
OrderedDict = dict
-def _abort():
- if not option('no_abort'):
- print 'Abort! (add --no_abort on the command line to avoid this
abortion)'
- sys.exit(1)
- else:
- print 'avoided abortion because of --no-abort'
-
def debugpr(out):
"""Add the text in string `out` to the log file (name in _log
variable)."""
@@ -25,6 +18,7 @@
from common import *
+from common import _abort # needs explicit import because of leading _
from misc import option, which
import html, latex, pdflatex, rst, sphinx, st, epytext, plaintext, gwiki,
mwiki, cwiki, pandoc, ipynb
@@ -2570,7 +2564,7 @@
names = supported_format_names()
if format not in names:
print '%s is not among the supported formats:\n%s' % (format,
names)
- sys.exit(1)
+ _abort()
encoding = option('encoding=', default='')
=======================================
--- /lib/doconce/gwiki.py Mon Mar 11 00:28:37 2013
+++ /lib/doconce/gwiki.py Fri Jun 28 09:22:02 2013
@@ -6,7 +6,7 @@
import re, os, commands, sys
-from common import default_movie, plain_exercise, insert_code_and_tex
+from common import default_movie, plain_exercise, insert_code_and_tex,
_abort
def gwiki_code(filestr, code_blocks, code_block_types,
tex_blocks, format):
@@ -38,7 +38,7 @@
if failure:
print '\n**** Warning: could not run', cmd
print 'Convert %s to PNG format manually' % filename
- sys.exit(1)
+ _abort()
filename = root + '.png'
caption = m.group('caption')
# keep label if it's there:
=======================================
--- /lib/doconce/html.py Mon Jun 24 11:00:38 2013
+++ /lib/doconce/html.py Fri Jun 28 09:22:02 2013
@@ -1,7 +1,7 @@
import re, os, glob, sys, glob
from common import table_analysis, plain_exercise, insert_code_and_tex, \
indent_lines, python_online_tutor, bibliography, \
- cite_with_multiple_args2multiple_cites
+ cite_with_multiple_args2multiple_cites, _abort
from misc import option
global _file_collection_filename
@@ -251,7 +251,7 @@
legal_styles += ['no', 'none']
if pygm_style not in legal_styles:
print 'pygments style "%s" is not legal, must be among\n%s' %
(pygm_style, ', '.join(legal_styles))
- #sys.exit(1)
+ #_abort()
print 'using the default style...'
pygm_style = 'default'
if pygm_style in ['no', 'none']:
@@ -266,7 +266,7 @@
if pygm is None:
print '*** error: cannot use Python Online Tutorial
(pyproopt)'
print ' without pygmentized code'
- sys.exit(1)
+ _abort()
code_blocks[i] = python_online_tutor(code_blocks[i],
return_tp='iframe')
@@ -504,14 +504,14 @@
# edit template_vargrant.html to template_mystyle.html
--html_template=template_mystyle.html
"""
- sys.exit(1)
+ _abort()
if 'template_vagrant.html' in template \
and not option('html_style=') == 'vagrant':
print """
*** error: --html_template= with a template based on
template_vagrant.html requires --html_style=vagrant
"""
- sys.exit(1)
+ _abort()
if template:
title = ''
@@ -544,11 +544,11 @@
if m:
title = m.group(1).strip()
filestr = re.sub(pattern, '\n<h1>%s</h1>\n' % title,
filestr)
-
- # Now use the first heading as title
- m = re.search(r'<h\d>(.+?)<a name=', filestr)
- if m:
- title = m.group(1).strip()
+ else:
+ # Use the first ordinary heading as title
+ m = re.search(r'<h\d>(.+?)<a name=', filestr)
+ if m:
+ title = m.group(1).strip()
# Extract date
pattern = r'<center><h\d>(.+?)</h\d></center>\s*<!-- date -->'
@@ -580,7 +580,7 @@
f = open(template, 'r'); template = f.read(); f.close()
except IOError:
print '*** error: could not find template "%s"' % template
- print 'Abort!'; sys.exit(1)
+ _abort()
# Check that template does not have "main content" begin and
# end lines that may interfere with the automatically generated
@@ -591,7 +591,7 @@
print ' with markers that doconce inserts - remove these'
for line in m:
print line
- print 'Abort!'; sys.exit(1)
+ _abort()
# template can only have slots for title, date, main
template = latin2html(template) # code non-ascii chars
@@ -746,7 +746,7 @@
plotfiles = glob.glob(filename)
if not plotfiles:
print 'No plotfiles on the form', filename
- sys.exit(1)
+ _abort()
plotfiles.sort()
basename = os.path.basename(plotfiles[0])
stem, ext = os.path.splitext(basename)
@@ -997,8 +997,7 @@
print e
print '*** error: problems in %s' % pubfile
print ' with key', label
- print 'Abort!'
- sys.exit(1)
+ _abort()
filestr = re.sub(r'^BIBFILE:.+$', bibtext, filestr,
flags=re.MULTILINE)
@@ -1261,7 +1260,7 @@
if body_font_family == '?' or body_font_family == 'help' or \
heading_font_family == '?' or heading_font_family == 'help':
print ' '.join(google_fonts)
- sys.exit(1)
+ _abort()
link = "@import url(http://fonts.googleapis.com/css?family=%s);"
import_body_font = ''
if body_font_family is not None:
=======================================
--- /lib/doconce/latex.py Mon Jun 24 11:00:38 2013
+++ /lib/doconce/latex.py Fri Jun 28 09:22:02 2013
@@ -4,7 +4,7 @@
from common import plain_exercise, table_analysis, \
_CODE_BLOCK, _MATH_BLOCK, doconce_exercise_output, indent_lines, \
python_online_tutor, envir_delimiter_lines, safe_join, \
- insert_code_and_tex
+ insert_code_and_tex, _abort
from misc import option
additional_packages = '' # comma-sep. list of packages for \usepackage{}
@@ -92,7 +92,7 @@
if current_code_envir is None:
# There should have been checks for this in doconce.py
print '*** errror: mismatch between !bc and !ec, line', i
- sys.exit(1)
+ _abort()
lines[i] = '\\b' + current_code_envir
if lines[i].startswith('!ec'):
lines[i] = '\\e' + current_code_envir
@@ -208,12 +208,12 @@
except IOError, e:
print 'tried to download %s, but failure:' % filename, e
print '*** error: cannot treat latex figure on the net (no
connection or invalid URL)'
- sys.exit(1)
+ _abort()
file_content = f.read()
f.close()
if 'DOCTYPE html' in file_content:
print '*** error: could not download', filename
- sys.exit(1)
+ _abort()
f = open(basename, 'w')
f.write(file_content)
f.close()
@@ -376,7 +376,7 @@
print 'Table has column alignment specification: %s, but %d
columns' \
% (column_spec, ncolumns)
print 'Table with rows', table['rows']
- sys.exit(1)
+ _abort()
# we do not support | in headings alignments (could be fixed,
# by making column_spec not a string but a list so the
@@ -386,7 +386,7 @@
print 'Table has headings alignment specification: %s, '\
'but %d columns' % (heading_spec, ncolumns)
print 'Table with rows', table['rows']
- sys.exit(1)
+ _abort()
s = '\n' + r'\begin{quote}\begin{tabular}{%s}' % column_spec + '\n'
for i, row in enumerate(table['rows']):
@@ -944,6 +944,15 @@
# _admon, _admon2rgb[_admon]))
+def latex_subsubsection(m):
+ title = m.group('subst').strip()
+ if title[-1] in ('?', '!', '.', ':',):
+ pass
+ else:
+ title += '.'
+ return r'\paragraph{%s}' % title
+
+
def latex_inline_comment(m):
name = m.group('name')
comment = m.group('comment')
@@ -1022,7 +1031,7 @@
'section': r'\section{\g<subst>}',
'subsection': r'\subsection{\g<subst>}',
#'subsubsection': '\n' + r'\subsubsection{\g<subst>}' + '\n',
- 'subsubsection': r'\paragraph{\g<subst>.}',
+ 'subsubsection': latex_subsubsection,
'paragraph': r'\paragraph{\g<subst>}\n',
#'abstract': '\n\n' + r'\\begin{abstract}' + '\n' +
r'\g<text>' + '\n' + r'\end{abstract}' + '\n\n' + r'\g<rest>', # not
necessary with separate \n
#'abstract':
r'\n\n\\begin{abstract}\n\g<text>\n\end{abstract}\n\n\g<rest>',
@@ -1429,7 +1438,7 @@
backgroundcolor=gray!5, %% white with 5%% gray
skipabove=\topsep,
skipbelow=\topsep,
- outerlinewidth=0.5,
+ outerlinewidth=0,
leftmargin=0,
rightmargin=0,
roundcorner=5,
=======================================
--- /lib/doconce/misc.py Mon Jun 24 11:00:38 2013
+++ /lib/doconce/misc.py Fri Jun 28 09:22:02 2013
@@ -1,4 +1,5 @@
import os, sys, shutil, re, glob, sets, time, commands
+from common import _abort
_registered_command_line_options = [
('--help',
@@ -126,11 +127,22 @@
option_name = '--' + name
if not option_name in _legal_command_line_options:
print 'test for illegal option:', option_name
- print 'Abort!'
- sys.exit(1)
+ _abort()
value = default
+ # Check if a command-line option has dash instead of underscore,
+ # which is a common mistake
+ for arg in sys.argv[1:]:
+ if arg.startswith('--'):
+ if '=' in arg:
+ arg = arg.split('=')[0] + '='
+ if arg not in _legal_command_line_options and \
+ ('--' + arg[2:].replace('-', '_')) in
_legal_command_line_options:
+ print 'found option %s, should be %s' % \
+ (arg, '--' + arg[2:].replace('-', '_'))
+ _abort()
+
# Check first if name is in configuration file (doconce_config)
name_dash2underscore = name.replace('-', '_')
if hasattr(doconce_config, name_dash2underscore):
@@ -171,8 +183,7 @@
if failure:
print 'could not run', cmd, failure_info
if abort_on_failure:
- print 'Abort!'
- sys.exit(1)
+ _abort()
def recommended_html_styles_and_pygments_styles():
"""
@@ -223,7 +234,7 @@
filename = sys.argv[1]
except IndexError:
print 'Usage: doconce remove_inline_comments myfile.do.txt'
- sys.exit(1)
+ _abort()
shutil.copy(filename, filename + '.old~~')
f = open(filename, 'r')
@@ -268,7 +279,7 @@
except IndexError:
print 'Usage: %s wikifile URL-stem' % sys.argv[0]
print 'Ex: %s somefile.gwiki
http://code.google.com/p/myproject/trunk/doc/somedir' % sys.argv[0]
- sys.exit(1)
+ _abort()
# first grep out all filenames with local path:
shutil.copy(gwikifile, gwikifile + '.old~~')
@@ -492,7 +503,7 @@
if os.path.splitext(filename)[1] != '.rst':
print 'Wrong filename extension in "%s" - must be a .rst file' \
% filename
- sys.exit(1)
+ _abort()
f = open(filename, 'r')
text = f.read()
@@ -1002,7 +1013,7 @@
filename
except:
print 'no specification of the .p.tex file'
- sys.exit(1)
+ _abort()
# Find which environments that will be defined and which
# latex packages that must be included.
@@ -1055,8 +1066,8 @@
if not os.path.isfile(filename + '.p.tex'):
- print 'No file %s' % (filename + '.p.tex')
- sys.exit(1)
+ print 'no file %s' % (filename + '.p.tex')
+ _abort()
output_filename = filename + '.tex'
cmd = 'preprocess %s %s > %s' % \
@@ -1114,7 +1125,7 @@
print 'You have requested the minted latex style, but this'
print 'requires the pygments package to be installed. On
Debian/Ubuntu: run'
print 'Terminal> sudo apt-get install python-pygments'
- sys.exit(1)
+ _abort()
# --- Treat the \code{} commands ---
@@ -1167,7 +1178,7 @@
filename = sys.argv[-1]
if not sys.argv[1].startswith('--from'):
print 'missing --from fromtext or --from_ fromtext option on the
command line'
- sys.exit(1)
+ _abort()
from_included = sys.argv[1] == '--from'
from_text = sys.argv[2]
@@ -1425,8 +1436,8 @@
cmd = 'iconv -f %s -t %s %s > %s' % \
(from_enc, to_enc, backupfile, filename)
else:
- print 'Changing encoding is not implemented on Windows machines'
- sys.exit(1)
+ print 'changing encoding is not implemented on Windows machines'
+ _abort()
os.rename(filename, backupfile)
system(cmd)
@@ -1668,8 +1679,8 @@
if not filename.endswith('.html'):
filename += '.html'
if not os.path.isfile(filename):
- print 'doconce file in html format, %s, does not exist - abort' %
filename
- sys.exit(1)
+ print 'doconce file in html format, %s, does not exist' % filename
+ _abort()
basename = os.path.basename(filename)
filestem = os.path.splitext(basename)[0]
@@ -1781,8 +1792,7 @@
print 'no width',
else:
print '%g' % width,
- print '\nAbort!'
- sys.exit(1)
+ _abort()
else:
width = 1./len(row)
for s, c in enumerate(row):
@@ -3124,7 +3134,7 @@
# the slide type is legal (before calling this function)
print '*** error: slide type "%s" is not known - abort' % slide_tp
print 'known slide
types:', ', '.join(list(all_combinations.keys()))
- sys.exit(1)
+ _abort()
# We need the subdir with reveal.js, deck.js, or similar to show
# the HTML slides so add the subdir to the registered file collection
@@ -3138,7 +3148,7 @@
print '*** error: %s theme "%s" is not known - abort' % \
(slide_tp, theme)
print 'known
themes:', ', '.join(list(all_combinations[slide_tp].keys()))
- sys.exit(1)
+ _abort()
m = re.search(r'<title>(.*?)</title>', ''.join(parts[0]))
if m:
@@ -3354,7 +3364,7 @@
filename += '.tex'
if not os.path.isfile(filename):
print 'doconce file in latex format, %s, does not exist - abort' %
filename
- sys.exit(1)
+ _abort()
basename = os.path.basename(filename)
filestem = os.path.splitext(basename)[0]
@@ -3754,7 +3764,7 @@
else:
print 'Syntax error in line'
print line
- sys.exit(1)
+ _abort()
print label
labels.append(label)
@@ -4217,8 +4227,8 @@
try:
f = open(filename, 'r')
except IOError:
- print '\nThe file %s does not exist!' % filename
- sys.exit(1)
+ print '\nfile %s does not exist!' % filename
+ _abort()
verbose = 1 if option('debug') else 0
@@ -5426,8 +5436,8 @@
from pygments.styles import get_all_styles
except ImportError:
pygm = None
- print 'pygments is not installed...abort'
- sys.exit(1)
+ print 'pygments is not installed'
+ _abort()
class DoconceLexer(RegexLexer):
"""
@@ -5840,8 +5850,8 @@
bibfiles = sys.argv[1:]
for bibfile in bibfiles:
if not bibfile.endswith('.bib'):
- print bibfile, 'is not a BibTeX file - abort'
- sys.exit(1)
+ print bibfile, 'is not a BibTeX file'
+ _abort()
shutil.copy(bibfile, bibfile + '.old~~')
f = open(bibfile, 'r')
lines = f.readlines()
@@ -5909,8 +5919,7 @@
print '*** error: broken line'
print lines[i]
print 'Glue with previous line!'
- print 'Abort!'
- sys.exit(1)
+ _abort()
f = open(bibfile, 'w')
f.writelines(lines)
@@ -6047,10 +6056,10 @@
if not os.path.isfile(fromfile):
print fromfile, 'does not exist'
- sys.exit(1)
+ _abort()
if not os.path.isfile(tofile):
print tofile, 'does not exist'
- sys.exit(1)
+ _abort()
fromdate = time.ctime(os.stat(fromfile).st_mtime)
todate = time.ctime(os.stat(tofile).st_mtime)
@@ -6159,7 +6168,7 @@
print 'diff in %s.pdf' % diff_file
else:
print program, 'not supported'
- sys.exit(1)
+ _abort()
def _usage_diffgit():
#print 'Usage: doconce gitdiff diffprog file1 file2 file3'
=======================================
--- /lib/doconce/mwiki.py Mon Jun 3 07:41:20 2013
+++ /lib/doconce/mwiki.py Fri Jun 28 09:22:02 2013
@@ -143,9 +143,9 @@
cmd = 'convert %s png:%s' % (filename, root+'.png')
failure, output = commands.getstatusoutput(cmd)
if failure:
- print '\n**** warning: could not run\n', cmd
- print 'Convert %s to PNG format manually' % filename
- sys.exit(1)
+ print '\n**** warning: could not run ', cmd
+ print ' convert %s to PNG format manually' % filename
+ _abort()
filename = root + '.png'
caption = m.group('caption').strip()
=======================================
--- /lib/doconce/plaintext.py Mon Mar 11 00:28:37 2013
+++ /lib/doconce/plaintext.py Fri Jun 28 09:22:02 2013
@@ -59,8 +59,8 @@
try:
bibdict = eval(bibstr)
except:
- print 'Error in Python dictionary for bibliography in', pyfile
- sys.exit(1)
+ print '*** error: in Python dictionary for bibliography in', pyfile
+ _abort()
text = '\n\n======= Bibliography =======\n\n'
for label in citations:
# remove newlines in reference data:
=======================================
--- /lib/doconce/rst.py Tue Jun 11 01:50:39 2013
+++ /lib/doconce/rst.py Fri Jun 28 09:22:02 2013
@@ -125,8 +125,7 @@
Still %s left after handling of code and tex blocks. Problem is probably
that %s is not preceded by text which can be extended with :: (required).
""" % (pattern, pattern)
- print 'Abort!'
- sys.exit(1)
+ _abort()
# Final fixes
Branch: default
Author: "Hans Petter Langtangen <h...@simula.no>"
Date: Fri Jun 28 09:22:02 2013
Log: Recompiled manuals. Moved _abort() function to common and it is
now used by all modules.
http://code.google.com/p/doconce/source/detail?r=17915e1da38e
Modified:
/doc/demos/manual/html/.buildinfo
/doc/demos/manual/html/_sources/manual.txt
/doc/demos/manual/html/_static/pygments.css
/doc/demos/manual/html/_static/searchtools.js
/doc/demos/manual/html/genindex.html
/doc/demos/manual/html/index.html
/doc/demos/manual/html/manual.html
/doc/demos/manual/html/search.html
/doc/demos/manual/html/searchindex.js
/doc/demos/manual/index.html
/doc/demos/manual/manual.cwiki
/doc/demos/manual/manual.do.txt
/doc/demos/manual/manual.epytext
/doc/demos/manual/manual.gwiki
/doc/demos/manual/manual.html
/doc/demos/manual/manual.md
/doc/demos/manual/manual.mwiki
/doc/demos/manual/manual.p.tex
/doc/demos/manual/manual.pdf
/doc/demos/manual/manual.rst
/doc/demos/manual/manual.rst.html
/doc/demos/manual/manual.rst.pdf
/doc/demos/manual/manual.rst.tex
/doc/demos/manual/manual.sphinx.rst
/doc/demos/manual/manual.tex
/doc/demos/manual/manual.txt
/doc/demos/manual/manual.xml
/doc/demos/manual/manual_pdflatex.pdf
/doc/manual/make.sh
/doc/manual/manual.do.txt
/lib/doconce/common.py
/lib/doconce/cwiki.py
/lib/doconce/doconce.py
/lib/doconce/gwiki.py
/lib/doconce/html.py
/lib/doconce/latex.py
/lib/doconce/misc.py
/lib/doconce/mwiki.py
/lib/doconce/plaintext.py
/lib/doconce/rst.py
=======================================
--- /doc/demos/manual/html/.buildinfo Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/.buildinfo Fri Jun 28 09:22:02 2013
@@ -1,4 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When
it is not found, a full rebuild will be done.
-config: b4c482109670ab5e81b9e005a0c806c3
+config: 3ea5c65044e09da28c0daa377b080bb4
tags: fbb0d17656682115ca4d033fb2f83ba1
=======================================
--- /doc/demos/manual/html/_sources/manual.txt Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/_sources/manual.txt Fri Jun 28 09:22:02 2013
@@ -5,7 +5,7 @@
===================
:Author: Hans Petter Langtangen
-:Date: May 29, 2013
+:Date: Jun 28, 2013
.. lines beginning with # are doconce comment lines
@@ -658,7 +658,7 @@
=============================
Transformation of a Doconce document ``mydoc.do.txt`` to various other
-formats applies the script ``doconce format``:
+formats apply the script ``doconce format``:
.. code-block:: console
@@ -2348,7 +2348,7 @@
(the label appears in the figure caption in the source code of this
document).
Additional references to the sections :ref:`mathtext`
and :ref:`newcommands` are
nice to demonstrate, as well as a reference to equations,
-say :eq:`myeq1`-:eq:`myeq2`. A comparison of the output and
+say (:ref:`myeq1`)-(:ref:`myeq2`). A comparison of the output and
the source of this document illustrates how labels and references
are handled by the format in question.
@@ -2500,7 +2500,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with ``===`` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in ``html`` output such that search engines can make use of the them.
Bibliography (2)
-----------------
@@ -2696,6 +2700,22 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes ``|`` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+
+.. code-block:: text
+
+
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+
+
Note that not all formats offer alignment of heading or entries
in tables (``rst`` and ``sphinx`` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2708,6 +2728,40 @@
where ``X`` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the ``doconce csv2table`` utility:
+
+
+.. code-block:: console
+
+ Terminal> doconce csv2table somefile.csv > table.do.txt
+
+This is a quick way of writing tables. For example, we can
+write a text file ``tmp.csv`` with
+
+
+.. code-block:: python
+
+ time, velocity, acceleration
+ 0.0, 1.4186, -5.01
+ 2.0, 1.376512, 11.919
+ 4.0, 1.1E+1, 14.717624
+
+Running ``doconce csv2table tmp.csv`` creates the table
+
+
+.. code-block:: text
+
+
+ |------c--------------c--------------c-------|
+ | time | velocity | acceleration |
+ |------c--------------c--------------c-------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------------------|
+
+
Exercises, Problems, Projects, and Examples
-------------------------------------------
@@ -3160,23 +3214,6 @@
\end{align}
!et
-Here is the result:
-
-
-.. math::
- :label: myeq1
-
- {\partial u\over\partial t} = \nabla^2 u + f,
-
-
-
-
-.. math::
- :label: myeq2
-
- {\partial v\over\partial t} = \nabla\cdot(q(u)\nabla v) + g.
-
-
The support of LaTeX mathematics varies among the formats:
@@ -3281,70 +3318,21 @@
newcommands in the ``newcommands*.tex`` files *must* appear on a single
line (multi-line newcommands are too hard to parse with regular
expressions).
-
-*Example.* Suppose we have the following commands in
-``newcommand_replace.tex``:
-
-
-.. code-block:: text
-
-
- \newcommand{\beqa}{\begin{eqnarray}}
- \newcommand{\eeqa}{\end{eqnarray}}
- \newcommand{\ep}{\thinspace . }
- \newcommand{\uvec}{\vec u}
- \newcommand{\Q}{\pmb{Q}}
-
-
-and these in ``newcommands_keep.tex``:
-
-
-.. code-block:: text
-
-
- \newcommand{\x}{\pmb{x}}
- \newcommand{\normalvec}{\pmb{n}}
- \newcommand{\Ddt}[1]{\frac{D#1}{dt}}
- \newcommand{\half}{\frac{1}{2}}
-The LaTeX block
-
-.. code-block:: text
-
-
- \beqa
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{\uvec} &=& \Q \ep label{my:eq2}
- \eeqa
-
-will then be rendered to
-
-.. math::
-
- \pmb{x}\cdot\pmb{n} &= 0, \\
- \frac{D{\vec u}{dt}} &= \pmb{Q} {\thinspace . }
-
-
-in the current format.
-
Admonitions
-----------
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-``block``, ``warning``, ``notice``, ``hint``, ``question``, and
``summary``.
-The box is defined by begin and end tags such as ``!bhint`` and ``!ehint``.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the ``hint`` environment gives a
-box with some admonition icon, text and/or colored background.)
+``block``, ``warning``, ``notice``, ``question``, and ``summary``.
+The box is defined by begin and end tags such as ``!bnotice`` and
``!enotice``.
The title of the box is fully customizable.
Here are a few examples:
@@ -3357,9 +3345,9 @@
Here is a warning!
!ewarning
- !bhint
+ !bnotice Hint
This is a hint.
- !ehint
+ !enotice
!bblock This is a block.
A block has never any icon.
@@ -3383,8 +3371,9 @@
.. warning::
Here is a warning!
+
+.. admonition:: Hint
-.. hint::
This is a hint.
@@ -3686,6 +3675,7 @@
Emacs Doconce Formatter
-----------------------
+
The file `.doconce-mode.el
<https://doconce.googlecode.com/hg/misc/.doconce-mode.el>`_ in the Doconce
source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3787,8 +3777,10 @@
.. font sizes are compatible
+
+Not yet written...
-Text is missing... Just a very preliminary sketch of commands:
+Just a very preliminary sketch of commands:
.. code-block:: console
@@ -3810,6 +3802,17 @@
LaTeX Beamer Slides
-------------------
+Not yet written...
+
+Themes
+~~~~~~
+
+Four themes come with Doconce: ``X_Y``, where ``X`` is ``blue`` or ``red``
+(the main color of the slides) and ``Y`` is `plain
<http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf>`_
+for simple layout and
+`shadow
<http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf>`_
+for shadowed boxes and more visual structure in the slides.
+
Mako Programming
================
@@ -3820,6 +3823,16 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+.. warning::
+ Unfortunately, the combination of Mako and LaTeX mathematics may
+ lead to problems because Mako applies syntax like ``${var}`` to extract
+ variables or call functions, while LaTeX mathematics sometimes applies
+ the same syntax, e.g., ``${\cal O}(\Delta x^2)$`` which looks like a
+ Mako function call. This problem can give rise to strange error
+ messages from Mako, usually that a variable is not defined.
+
+
The Basics of Mako
------------------
@@ -4015,6 +4028,16 @@
General Problems
----------------
+Spellcheck reports a lot of mistakes related LaTeX math
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``doconce spellcheck`` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant ``tmp_missing_*`` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
Doconce aborts because of a syntax error that is not an error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4042,6 +4065,27 @@
* Strings with ``'T<%.1f'`` look as openings of Mako blocks (``<%``);
change
to ``'T < %.1f'`` to avoid this confusion.
+The Mako preprocessor claims a variable is undefined
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, :math:`{\cal O}(\Delta x^2)` is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use ``${`` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is ``${}^+$`` type of indication of superscripts.
+A suggested rewrite is ``$\,{}^+$``.
+
+The error message will ask you to rerun ``doconce`` with
+``--mako_strict_undefined``, which will display the variable that
+is confusing Mako. However, do not continue to use
+``--mako_strict_undefined`` while you are debugging because this
+variable will then always be undefined in that mode.
+Use ``# #ifdef`` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without ``--mako_strict_undefined``).
+
Something goes wrong in the preprocessing step
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4512,6 +4556,16 @@
Problems with HTML Output
-------------------------
+MathJax formulas are not properly rendered
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ * ``[`` and ``]`` brackets must sometimes be replaced by ``\lbrack`` and
``\rbrack``
+
How can I change the layout of the HTML page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================
--- /doc/demos/manual/html/_static/pygments.css Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/_static/pygments.css Fri Jun 28 09:22:02 2013
@@ -13,11 +13,11 @@
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
-.highlight .go { color: #303030 } /* Generic.Output */
+.highlight .go { color: #333333 } /* Generic.Output */
.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading
*/
-.highlight .gt { color: #0040D0 } /* Generic.Traceback */
+.highlight .gt { color: #0044DD } /* Generic.Traceback */
.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #007020; font-weight: bold } /*
Keyword.Declaration */
.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace
*/
=======================================
--- /doc/demos/manual/html/_static/searchtools.js Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/_static/searchtools.js Fri Jun 28 09:22:02 2013
@@ -301,7 +301,7 @@
},
query : function(query) {
- var stopwords =
["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"];
+ var stopwords =
["and","then","into","it","as","are","in","if","for","no","there","their","was","is","be","to","that","but","they","not","such","with","by","a","on","these","of","will","this","near","the","or","at"];
// Stem the searchterms and add them to the correct list
var stemmer = new Stemmer();
=======================================
--- /doc/demos/manual/html/genindex.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/genindex.html Fri Jun 28 09:22:02 2013
@@ -17,7 +17,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
- URL_ROOT: './',
+ URL_ROOT: '',
VERSION: '0.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
@@ -267,7 +267,7 @@
</div>
<div class="footer">
© Copyright 2013, HPL.
- Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2pre.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
=======================================
--- /doc/demos/manual/html/index.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/index.html Fri Jun 28 09:22:02 2013
@@ -15,7 +15,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
- URL_ROOT: './',
+ URL_ROOT: '',
VERSION: '0.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
@@ -202,7 +202,7 @@
</div>
<div class="footer">
© Copyright 2013, HPL.
- Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2pre.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
=======================================
--- /doc/demos/manual/html/manual.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/manual.html Fri Jun 28 09:22:02 2013
@@ -15,7 +15,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
- URL_ROOT: './',
+ URL_ROOT: '',
VERSION: '0.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
@@ -56,7 +56,7 @@
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Author:</th><td
class="field-body">Hans Petter Langtangen</td>
</tr>
-<tr class="field-even field"><th class="field-name">Date:</th><td
class="field-body">May 29, 2013</td>
+<tr class="field-even field"><th class="field-name">Date:</th><td
class="field-body">Jun 28, 2013</td>
</tr>
</tbody>
</table>
@@ -562,7 +562,7 @@
<div class="section" id="from-doconce-to-other-formats">
<span id="doconce2formats"></span><h1>From Doconce to Other Formats<a
class="headerlink" href="#from-doconce-to-other-formats" title="Permalink
to this headline">¶</a></h1>
<p>Transformation of a Doconce document <tt class="docutils literal"><span
class="pre">mydoc.do.txt</span></tt> to various other
-formats applies the script <tt class="docutils literal"><span
class="pre">doconce</span> <span class="pre">format</span></tt>:</p>
+formats apply the script <tt class="docutils literal"><span
class="pre">doconce</span> <span class="pre">format</span></tt>:</p>
<div class="highlight-console"><div class="highlight"><pre><span
class="go">Terminal> doconce format format mydoc.do.txt</span>
</pre></div>
</div>
@@ -1537,7 +1537,7 @@
part of the caption appearing on the same line as <tt class="docutils
literal"><span class="pre">FIGURE:</span></tt> will be
included in the formatted caption).</p>
<div class="figure" id="fig-viz">
-<a class="reference internal image-reference"
href="_images/streamtubes.png"><img alt="_images/streamtubes.png"
src="_images/streamtubes.png" style="width: 400px;" /></a>
+<img alt="_images/streamtubes.png" src="_images/streamtubes.png"
style="width: 400px;" />
<p class="caption"><em>Streamtube visualization of a fluid flow</em></p>
</div>
<p>Combining several image files into one, in a table fashion, can be done
by the
@@ -1827,7 +1827,7 @@
(the label appears in the figure caption in the source code of this
document).
Additional references to the sections <a class="reference internal"
href="#mathtext"><em>LaTeX Blocks of Mathematical Text</em></a> and <a
class="reference internal" href="#newcommands"><em>Macros
(Newcommands)</em></a> are
nice to demonstrate, as well as a reference to equations,
-say <a href="#equation-myeq1">(1)</a>-<a href="#equation-myeq2">(2)</a>. A
comparison of the output and
+say (<em class="xref std std-ref">myeq1</em>)-(<em class="xref std
std-ref">myeq2</em>). A comparison of the output and
the source of this document illustrates how labels and references
are handled by the format in question.</p>
<p>Hyperlinks to files or web addresses are handled as explained
@@ -1937,7 +1937,10 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).</p>
+LaTeX is the output format). For paragraphs with <tt class="docutils
literal"><span class="pre">===</span></tt> heading,
+the index keywords should be placed above the heading.</p>
+<p>The keywords in the index are automatically placed in a meta
+tag in <tt class="docutils literal"><span class="pre">html</span></tt>
output such that search engines can make use of the them.</p>
</div>
<div class="section" id="bibliography-2">
<h2>Bibliography (2)<a class="headerlink" href="#bibliography-2"
title="Permalink to this headline">¶</a></h2>
@@ -2113,7 +2116,18 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes <tt class="docutils literal"><span class="pre">|
</span></tt> can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
-Note that not all formats offer alignment of heading or entries
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like</p>
+<div class="highlight-text"><div class="highlight"><pre>|
--c--------c-----------c--------|
+|time | velocity | acceleration |
+|--l--------r-----------r--------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------|
+</pre></div>
+</div>
+<p>Note that not all formats offer alignment of heading or entries
in tables (<tt class="docutils literal"><span class="pre">rst</span></tt>
and <tt class="docutils literal"><span class="pre">sphinx</span></tt> are
examples). Also note that
Doconce tables are very simple: neither entries nor
headings can span several columns or rows. When that functionality
@@ -2123,6 +2137,29 @@
makes Doconce dump each table to CSV format in a file <tt class="docutils
literal"><span class="pre">table_X.csv</span></tt>,
where <tt class="docutils literal"><span class="pre">X</span></tt> is the
table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.</p>
+<p>Data in CSV format can be transformed to Doconce table format
+by the <tt class="docutils literal"><span class="pre">doconce</span> <span
class="pre">csv2table</span></tt> utility:</p>
+<div class="highlight-console"><div class="highlight"><pre><span
class="go">Terminal> doconce csv2table somefile.csv >
table.do.txt</span>
+</pre></div>
+</div>
+<p>This is a quick way of writing tables. For example, we can
+write a text file <tt class="docutils literal"><span
class="pre">tmp.csv</span></tt> with</p>
+<div class="highlight-python"><div class="highlight"><pre><span
class="n">time</span><span class="p">,</span> <span
class="n">velocity</span><span class="p">,</span> <span
class="n">acceleration</span>
+<span class="mf">0.0</span><span class="p">,</span> <span
class="mf">1.4186</span><span class="p">,</span> <span
class="o">-</span><span class="mf">5.01</span>
+<span class="mf">2.0</span><span class="p">,</span> <span
class="mf">1.376512</span><span class="p">,</span> <span
class="mf">11.919</span>
+<span class="mf">4.0</span><span class="p">,</span> <span
class="mf">1.1E+1</span><span class="p">,</span> <span
class="mf">14.717624</span>
+</pre></div>
+</div>
+<p>Running <tt class="docutils literal"><span class="pre">doconce</span>
<span class="pre">csv2table</span> <span class="pre">tmp.csv</span></tt>
creates the table</p>
+<div class="highlight-text"><div class="highlight"><pre>|
------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+</pre></div>
+</div>
</div>
<div class="section" id="exercises-problems-projects-and-examples">
<h2>Exercises, Problems, Projects, and Examples<a class="headerlink"
href="#exercises-problems-projects-and-examples" title="Permalink to this
headline">¶</a></h2>
@@ -2377,7 +2414,7 @@
</pre></div>
</div>
<p>And here is a C++ code snippet (<tt class="docutils literal"><span
class="pre">cppcod</span></tt> style):</p>
-<div class="highlight-c++"><div class="highlight"><pre><span
class="kt">void</span> <span class="n">myfunc</span><span
class="p">(</span><span class="kt">double</span><span class="o">*</span>
<span class="n">x</span><span class="p">,</span> <span
class="k">const</span> <span class="kt">double</span><span
class="o">&</span> <span class="n">myarr</span><span class="p">)</span>
<span class="p">{</span>
+<div class="highlight-c++"><div class="highlight"><pre><span
class="kt">void</span> <span class="nf">myfunc</span><span
class="p">(</span><span class="kt">double</span><span class="o">*</span>
<span class="n">x</span><span class="p">,</span> <span
class="k">const</span> <span class="kt">double</span><span
class="o">&</span> <span class="n">myarr</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">for</span> <span class="p">(</span><span
class="kt">int</span> <span class="n">i</span> <span class="o">=</span>
<span class="mi">1</span><span class="p">;</span> <span class="n">i</span>
<span class="o"><</span> <span class="n">myarr</span><span
class="p">.</span><span class="n">size</span><span class="p">();</span>
<span class="n">i</span><span class="o">++</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">myarr</span><span class="p">[</span><span
class="n">i</span><span class="p">]</span> <span class="o">=</span> <span
class="n">myarr</span><span class="p">[</span><span class="n">i</span><span
class="p">]</span> <span class="o">-</span> <span class="n">x</span><span
class="p">[</span><span class="n">i</span><span class="p">]</span><span
class="o">*</span><span class="n">myarr</span><span class="p">[</span><span
class="n">i</span><span class="o">-</span><span class="mi">1</span><span
class="p">]</span>
<span class="p">}</span>
@@ -2485,11 +2522,6 @@
!et
</pre></div>
</div>
-<p>Here is the result:</p>
-<div class="math" id="equation-myeq1">
-<span class="eqno">(1)</span>\[ {\partial u\over\partial t} = \nabla^2
u + f,\]</div>
-<div class="math" id="equation-myeq2">
-<span class="eqno">(2)</span>\[ {\partial v\over\partial t} =
\nabla\cdot(q(u)\nabla v) + g.\]</div>
<p>The support of LaTeX mathematics varies among the formats:</p>
<blockquote>
<div><ul class="simple">
@@ -2579,59 +2611,27 @@
newcommands in the <tt class="docutils literal"><span
class="pre">newcommands*.tex</span></tt> files <em>must</em> appear on a
single
line (multi-line newcommands are too hard to parse with regular
expressions).</p>
-<p><em>Example.</em> Suppose we have the following commands in
-<tt class="docutils literal"><span
class="pre">newcommand_replace.tex</span></tt>:</p>
-<div class="highlight-text"><div
class="highlight"><pre>\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-</pre></div>
-</div>
-<p>and these in <tt class="docutils literal"><span
class="pre">newcommands_keep.tex</span></tt>:</p>
-<div class="highlight-text"><div
class="highlight"><pre>\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-</pre></div>
-</div>
-<p>The LaTeX block</p>
-<div class="highlight-text"><div class="highlight"><pre>\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-</pre></div>
-</div>
-<p>will then be rendered to</p>
-<div class="math">
-\[\begin{split}\pmb{x}\cdot\pmb{n} &= 0, \\
-\frac{D{\vec u}{dt}} &= \pmb{Q} {\thinspace . }\end{split}\]</div>
-<p>in the current format.</p>
</div>
<div class="section" id="admonitions">
<h2>Admonitions<a class="headerlink" href="#admonitions" title="Permalink
to this headline">¶</a></h2>
<p>Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.</p>
<p>The following admonition environments are available:
-<tt class="docutils literal"><span class="pre">block</span></tt>, <tt
class="docutils literal"><span class="pre">warning</span></tt>, <tt
class="docutils literal"><span class="pre">notice</span></tt>, <tt
class="docutils literal"><span class="pre">hint</span></tt>, <tt
class="docutils literal"><span class="pre">question</span></tt>, and <tt
class="docutils literal"><span class="pre">summary</span></tt>.
-The box is defined by begin and end tags such as <tt class="docutils
literal"><span class="pre">!bhint</span></tt> and <tt class="docutils
literal"><span class="pre">!ehint</span></tt>.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading <em>Hint</em> (with number)
-appears, while outside exercises the <tt class="docutils literal"><span
class="pre">hint</span></tt> environment gives a
-box with some admonition icon, text and/or colored background.)
+<tt class="docutils literal"><span class="pre">block</span></tt>, <tt
class="docutils literal"><span class="pre">warning</span></tt>, <tt
class="docutils literal"><span class="pre">notice</span></tt>, <tt
class="docutils literal"><span class="pre">question</span></tt>, and <tt
class="docutils literal"><span class="pre">summary</span></tt>.
+The box is defined by begin and end tags such as <tt class="docutils
literal"><span class="pre">!bnotice</span></tt> and <tt class="docutils
literal"><span class="pre">!enotice</span></tt>.
The title of the box is fully customizable.</p>
<p>Here are a few examples:</p>
<div class="highlight-text"><div class="highlight"><pre>!bwarning
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -2655,7 +2655,7 @@
<p class="first admonition-title">Warning</p>
<p class="last">Here is a warning!</p>
</div>
-<div class="admonition hint">
+<div class="admonition-hint admonition">
<p class="first admonition-title">Hint</p>
<p class="last">This is a hint.</p>
</div>
@@ -3024,7 +3024,8 @@
</div>
<div class="section" id="html5-slides">
<h2>HTML5 Slides<a class="headerlink" href="#html5-slides"
title="Permalink to this headline">¶</a></h2>
-<p>Text is missing... Just a very preliminary sketch of commands:</p>
+<p>Not yet written...</p>
+<p>Just a very preliminary sketch of commands:</p>
<div class="highlight-console"><div class="highlight"><pre><span
class="go">Terminal> doconce format html myslides \</span>
<span class="go"> --pygments_html_style=native
--keep_pygments_html_bg</span>
<span class="go">Terminal> doconce slides_html myslides reveal \</span>
@@ -3045,6 +3046,15 @@
</div>
<div class="section" id="latex-beamer-slides">
<h2>LaTeX Beamer Slides<a class="headerlink" href="#latex-beamer-slides"
title="Permalink to this headline">¶</a></h2>
+<p>Not yet written...</p>
+<div class="section" id="themes">
+<h3>Themes<a class="headerlink" href="#themes" title="Permalink to this
headline">¶</a></h3>
+<p>Four themes come with Doconce: <tt class="docutils literal"><span
class="pre">X_Y</span></tt>, where <tt class="docutils literal"><span
class="pre">X</span></tt> is <tt class="docutils literal"><span
class="pre">blue</span></tt> or <tt class="docutils literal"><span
class="pre">red</span></tt>
+(the main color of the slides) and <tt class="docutils literal"><span
class="pre">Y</span></tt> is <a class="reference external"
href="http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf">plain</a>
+for simple layout and
+<a class="reference external"
href="http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf">shadow</a>
+for shadowed boxes and more visual structure in the slides.</p>
+</div>
</div>
</div>
<div class="section" id="mako-programming">
@@ -3055,6 +3065,15 @@
sufficient for if-else tests to steer which parts of the text that
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Unfortunately, the combination of Mako and LaTeX
mathematics may
+lead to problems because Mako applies syntax like <tt class="docutils
literal"><span class="pre">${var}</span></tt> to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., <tt class="docutils literal"><span
class="pre">${\cal</span> <span class="pre">O}(\Delta</span> <span
class="pre">x^2)$</span></tt> which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.</p>
+</div>
<div class="section" id="the-basics-of-mako">
<h2>The Basics of Mako<a class="headerlink" href="#the-basics-of-mako"
title="Permalink to this headline">¶</a></h2>
<p>Just a preliminary sketch of some Mako code (next example is
better!):</p>
@@ -3222,6 +3241,15 @@
</div>
<div class="section" id="general-problems">
<h2>General Problems<a class="headerlink" href="#general-problems"
title="Permalink to this headline">¶</a></h2>
+<div class="section"
id="spellcheck-reports-a-lot-of-mistakes-related-latex-math">
+<h3>Spellcheck reports a lot of mistakes related LaTeX math<a
class="headerlink"
href="#spellcheck-reports-a-lot-of-mistakes-related-latex-math"
title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">doconce</span> <span
class="pre">spellcheck</span></tt> command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant <tt class="docutils literal"><span
class="pre">tmp_missing_*</span></tt> file and search for the math
expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.</p>
+</div>
<div class="section"
id="doconce-aborts-because-of-a-syntax-error-that-is-not-an-error">
<h3>Doconce aborts because of a syntax error that is not an error<a
class="headerlink"
href="#doconce-aborts-because-of-a-syntax-error-that-is-not-an-error"
title="Permalink to this headline">¶</a></h3>
<p>Doconce searches for typical syntax errors and usually aborts the
@@ -3249,6 +3277,25 @@
</ul>
</div></blockquote>
</div>
+<div class="section"
id="the-mako-preprocessor-claims-a-variable-is-undefined">
+<h3>The Mako preprocessor claims a variable is undefined<a
class="headerlink"
href="#the-mako-preprocessor-claims-a-variable-is-undefined"
title="Permalink to this headline">¶</a></h3>
+<p>Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, <span class="math">\({\cal O}(\Delta x^2)\)</span> is valid
LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use <tt class="docutils literal"><span
class="pre">${</span></tt> anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is <tt class="docutils literal"><span
class="pre">${}^+$</span></tt> type of indication of superscripts.
+A suggested rewrite is <tt class="docutils literal"><span
class="pre">$\,{}^+$</span></tt>.</p>
+<p>The error message will ask you to rerun <tt class="docutils
literal"><span class="pre">doconce</span></tt> with
+<tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt>, which will display the
variable that
+is confusing Mako. However, do not continue to use
+<tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt> while you are debugging
because this
+variable will then always be undefined in that mode.
+Use <tt class="docutils literal"><span class="pre">#</span> <span
class="pre">#ifdef</span></tt> directives to comment out large portions of
+the text and apply a “bisection” procedure to locate where
+the Mako problem is (without <tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt>).</p>
+</div>
<div class="section" id="something-goes-wrong-in-the-preprocessing-step">
<h3>Something goes wrong in the preprocessing step<a class="headerlink"
href="#something-goes-wrong-in-the-preprocessing-step" title="Permalink to
this headline">¶</a></h3>
<p>You can examine <tt class="docutils literal"><span
class="pre">tmp_preprocess__filename</span></tt> and <tt class="docutils
literal"><span class="pre">tmp_mako__filename</span></tt>,
@@ -3623,6 +3670,17 @@
</div>
<div class="section" id="problems-with-html-output">
<h2>Problems with HTML Output<a class="headerlink"
href="#problems-with-html-output" title="Permalink to this
headline">¶</a></h2>
+<div class="section" id="mathjax-formulas-are-not-properly-rendered">
+<h3>MathJax formulas are not properly rendered<a class="headerlink"
href="#mathjax-formulas-are-not-properly-rendered" title="Permalink to this
headline">¶</a></h3>
+<p>Here are some common problems:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Two equations cannot have identical label (this error often arises
+from copying and pasting equations)</li>
+<li><tt class="docutils literal"><span class="pre">[</span></tt> and <tt
class="docutils literal"><span class="pre">]</span></tt> brackets must
sometimes be replaced by <tt class="docutils literal"><span
class="pre">\lbrack</span></tt> and <tt class="docutils literal"><span
class="pre">\rbrack</span></tt></li>
+</ul>
+</div></blockquote>
+</div>
<div class="section" id="how-can-i-change-the-layout-of-the-html-page">
<h3>How can I change the layout of the HTML page?<a class="headerlink"
href="#how-can-i-change-the-layout-of-the-html-page" title="Permalink to
this headline">¶</a></h3>
<p>The easiest way is to edit the HTML style or the HTML code directly.
@@ -3919,7 +3977,10 @@
<li><a class="reference internal" href="#potential-problems">Potential
Problems</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#latex-beamer-slides">LaTeX Beamer
Slides</a></li>
+<li><a class="reference internal" href="#latex-beamer-slides">LaTeX Beamer
Slides</a><ul>
+<li><a class="reference internal" href="#themes">Themes</a></li>
+</ul>
+</li>
</ul>
</li>
<li><a class="reference internal" href="#mako-programming">Mako
Programming</a><ul>
@@ -3930,9 +3991,11 @@
<li><a class="reference internal"
href="#troubleshooting">Troubleshooting</a><ul>
<li><a class="reference internal" href="#disclaimer">Disclaimer</a></li>
<li><a class="reference internal" href="#general-problems">General
Problems</a><ul>
+<li><a class="reference internal"
href="#spellcheck-reports-a-lot-of-mistakes-related-latex-math">Spellcheck
reports a lot of mistakes related LaTeX math</a></li>
<li><a class="reference internal"
href="#doconce-aborts-because-of-a-syntax-error-that-is-not-an-error">Doconce
aborts because of a syntax error that is not an error</a></li>
<li><a class="reference internal"
href="#the-mako-preprocessor-is-seemingly-not-run">The Mako preprocessor is
seemingly not run</a></li>
<li><a class="reference internal"
href="#the-mako-preprocessor-is-fooled-by-doconce-text">The Mako
preprocessor is fooled by Doconce text</a></li>
+<li><a class="reference internal"
href="#the-mako-preprocessor-claims-a-variable-is-undefined">The Mako
preprocessor claims a variable is undefined</a></li>
<li><a class="reference internal"
href="#something-goes-wrong-in-the-preprocessing-step">Something goes wrong
in the preprocessing step</a></li>
<li><a class="reference internal"
href="#figure-captions-are-incomplete">Figure captions are
incomplete</a></li>
<li><a class="reference internal"
href="#preprocessor-directives-do-not-work">Preprocessor directives do not
work</a></li>
@@ -3986,6 +4049,7 @@
</ul>
</li>
<li><a class="reference internal"
href="#problems-with-html-output">Problems with HTML Output</a><ul>
+<li><a class="reference internal"
href="#mathjax-formulas-are-not-properly-rendered">MathJax formulas are not
properly rendered</a></li>
<li><a class="reference internal"
href="#how-can-i-change-the-layout-of-the-html-page">How can I change the
layout of the HTML page?</a></li>
<li><a class="reference internal"
href="#why-do-figures-look-ugly-when-using-html-templates">Why do figures
look ugly when using HTML templates?</a></li>
</ul>
@@ -4040,7 +4104,7 @@
</div>
<div class="footer">
© Copyright 2013, HPL.
- Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2pre.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
=======================================
--- /doc/demos/manual/html/search.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/search.html Fri Jun 28 09:22:02 2013
@@ -15,7 +15,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
- URL_ROOT: './',
+ URL_ROOT: '',
VERSION: '0.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
@@ -94,7 +94,7 @@
</div>
<div class="footer">
© Copyright 2013, HPL.
- Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2pre.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
=======================================
--- /doc/demos/manual/html/searchindex.js Wed May 29 03:54:41 2013
+++ /doc/demos/manual/html/searchindex.js Fri Jun 28 09:22:02 2013
@@ -1,1 +1,1 @@
-Search.setIndex({objects:{},terms:{mydoc2:1,linebreak:1,beqa:1,yellow:1,four:1,fig2:1,fig3:1,fig1:1,thinspac:1,consider:1,spellcheck:1,ecollin:1,usepackag:1,matlab:1,under:1,preprocess:[0,1],yourdoc:1,everi:1,wrapper_tech:1,"void":1,theorem_count:1,affect:1,pygments_html_lineno:1,disturb:1,eqnarrai:1,upload:1,vector:1,darkgrai:1,relsiz:1,dirnam:1,direct:1,consequ:1,second:1,esol:1,blue:1,mpeg:1,extra_sect:1,"new":1,net:1,never:1,here:1,"const":1,python_an:1,interpret:1,forum:1,ptex2tex:1,precis:1,loop:1,studi:1,brought:1,unix:1,org:1,outro:1,txt:1,shcod:1,describ:1,would:1,includemovi:1,doconc:[0,1],call:1,recommend:1,calc:1,type:1,pdfcrop:1,relat:1,footerbgcolor:1,notic:1,warn:1,mwk:1,rootdir:1,si2uchh3qim:1,automake_sphinx:1,must:1,springer:1,word:1,setup:1,work:1,split_rst:1,root:1,overrid:1,give:1,da6pap:1,caution:1,want:1,attract:1,end:1,quot:1,ordinari:1,vagrant:1,how:1,answer:1,perspect:1,updat:1,recogn:1,after:1,befor:1,wrong:1,demonstr:1,basicstrap:1,attempt:1,pdfnup:1,bootstrap:1,mwiki:1,neglect:1,myeq1:1,maintain:1,environ:[0,1],eblock:1,enter:1,order:1,srclib:1,deck:1,over:1,becaus:1,jpeg:1,keyboard:1,flexibl:1,vari:1,myfil:1,fit:1,setspac:1,better:1,offic:1,fig:1,comprehens:1,html_style:1,easier:1,miiton:1,them:1,var1:1,thei:1,safe:1,"break":1,yourself:1,choic:1,sphinxext:1,each:1,debug:[0,1],side:1,mean:1,pdflatex:[0,1],laboratori:1,logg:1,extract:1,goe:1,content:[0,1],fairli:1,sphinx_dir:1,reader:1,forth:1,linear:1,navig:1,situat:1,standard:1,acrobat:1,reformul:1,bwarn:1,argument:[0,1],filter:1,iso:1,examples_as_exercis:1,onto:1,no_pygments_html:1,"__theorem":1,rang:1,html_theme_opt:1,render:1,independ:1,biomed:1,restrict:1,instruct:1,alreadi:1,"__abstract":1,primari:1,top:1,sometim:1,mercuri:1,underlin:1,master:1,too:1,similarli:1,toc:1,consol:1,tool:1,xkeyval:1,somewhat:1,knob:1,simula:1,solvin:1,charcter:1,past:1,target:1,keyword:1,provid:1,eq2:1,tree:1,usepack:1,project:[0,1],doonc:1,"5mm":1,admonit:[0,1],fashion:1,dvar1:1,modern:1,raw:1,pylon:1,seen:1,mint:1,minu:1,minted_cpp:1,latter:1,even:1,though:1,pdiff:1,ebook:1,regular:1,letter:1,choos:1,style_vagr:1,tradit:1,don:1,doc:1,flow:1,doe:1,dummi:1,abbrev:1,declar:1,unchang:1,winther:1,random:1,pygments_html_styl:1,syntax:1,mediawiki:1,indentend:1,theme_dir:1,involv:1,layout:1,explain:1,configur:1,theme:1,rich:1,shoutwiki:1,agni:1,watch:1,fluid:1,encourg:1,cloud_spthem:1,makeindex:1,report:1,keyword2:1,keyword1:1,youtub:1,briefer:1,emb:1,"public":1,ban:1,respond:1,exericis:1,kolmogorov:1,pdftool:1,result:1,fail:1,best:1,awar:1,databas:1,wikipedia:1,figur:[0,1],simplest:1,awai:1,approach:1,accord:1,slides_beam:1,extend:1,extens:1,lazi:1,preprocessor:1,extent:1,toler:1,han:1,howev:1,subitem:1,cod:1,docbook:1,seri:1,com:1,mardal:1,dbook:1,height:1,stylefil:1,documentstyl:1,path:1,diff:1,guid:1,assum:1,summar:1,duplic:1,union:1,numpi:1,three:1,been:1,much:1,sphinxdir:1,basic:[0,1],quickli:1,life:1,deeper:1,spit:1,xxy:1,xxx:1,anywher:1,els:1,emploi:1,ugli:1,subentri:1,gnu:1,servic:1,properti:1,sourceforg:1,aim:1,dept:1,aid:1,anchor:1,pyramid:1,coher:1,conv:1,a6pap:1,conf:1,sever:1,mako:[0,1],disabl:1,perform:1,suggest:1,make:1,complex:1,split:[0,1],texinfo:1,complet:1,a2p:1,slides_html:1,mytext:1,hand:1,bibliograph:1,norwegian:1,pngmath_dvipng_arg:1,tune:1,moondist:1,redefin:1,kept:1,thi:1,endif:1,everyth:1,giftran:1,left:1,identifi:1,just:1,rst2odt:1,xelatex:[0,1],human:1,ifdef:1,kdiff3:1,yet:1,languag:[0,1],easi:1,mix:1,interfer:1,fortran:1,cp2texmf:1,save:1,explanatori:1,gave:1,mayb:1,boldfac:1,fromto:1,background:1,shadow:1,wrapfig:1,measur:1,amon:1,specif:1,arbitrari:1,manual:[0,1],docutil:1,www:1,right:1,old:1,intern:1,toctre:1,successfulli:1,total:1,collect:1,univ:1,core:1,plu:1,bold:1,fancyvrb:1,repositori:1,post:[0,1],chapter:1,slightli:1,surround:1,algn:1,"__proof":1,produc:1,ppa:1,"float":1,encod:1,fancybox:1,down:1,wrap:1,accordingli:1,git:1,perldoc:1,suffici:1,support:1,transform:1,why:1,avail:1,width:1,wordpress:1,editor:1,analysi:1,head:1,satisfactorili:1,form:1,offer:1,solar:1,"true":1,featur:[0,1],classic:1,request:1,"abstract":1,ephas:1,postscript:1,exist:1,check:1,assembl:1,somenam:1,tkdiff:1,eremark:1,when:1,test:1,diffpack:1,matur:1,notif:1,intend:1,asterisk:1,consid:1,occasion:1,stoke:1,bitbucket:1,longer:1,bullet:1,phone:1,ignor:1,maxdepth:1,time:1,beamer:[0,1],nxn:1,concept:1,particular:1,row:1,middl:1,depend:[0,1],unnumb:1,flask:1,vec:1,texmf:1,proj:1,sourc:[0,1],xpro:1,brows:1,seemingli:1,level:1,did:1,relbarbgcolor:1,iter:1,item:1,preprocesor:1,combine_imag:1,team:1,quick:[0,1],sidebarlinkcolor:1,round:1,dir:1,sign:1,pmb:1,dmath:1,appear:1,anywai:1,current:1,rst2xml:1,meld:1,xml:1,autogener:1,gener:[0,1],disclaim:[0,1],modif:1,address:1,locat:1,along:1,box:1,shift:1,trial:1,behav:1,myvar:1,slidecel:1,extra:1,tweak:[0,1],modul:[0,1],ipi:1,prefer:1,backtick:1,visibl:1,instal:[0,1],should:1,regex:1,dvipdf:1,univers:1,helvetica:1,todai:1,subvers:1,stylesheet:1,criteria:1,checkout:1,share:1,newcommand:[0,1],visual:1,appendix:1,indic:[0,1],examin:1,easiest:1,dhelvetica:1,slogan:1,uniqu:1,impel:1,can:1,purpos:1,ehint:1,encapsul:1,bloodish:1,backslash:1,topic:1,abort:1,occur:1,alwai:1,differenti:1,multipl:1,oslo:1,no_abort:1,write:[0,1],pure:1,tile:1,ispel:1,map:1,clone:1,codetermin:1,mac:1,mai:1,underscor:1,data:1,man:1,mdframe:1,favorit:1,inform:1,"switch":1,cannot:1,combin:1,ssh:1,epydoc:1,boldface_:1,"_part0000_mydoc":1,equip:1,still:1,mainli:1,dynam:1,entiti:1,group:1,passag:1,platform:1,window:1,doconce_head:1,main:1,non:1,recal:1,matcher:1,initi:1,half:1,now:1,discuss:1,nor:1,name:1,config:1,separ:1,mydoc_html_file_collect:1,admon:1,compil:1,f2f2f2:1,replac:1,individu:1,continu:1,backport:1,year:1,happen:1,reportlab:1,space:1,bnotic:1,sespecif:1,formula:1,md2html:1,correct:1,headlin:1,fontsiz:1,institut:1,care:1,"__a":1,wai:1,modest:1,thing:1,place:1,view:1,nicknam:1,imposs:1,frequent:1,first:1,origin:1,directli:1,carri:1,onc:1,arrai:1,bluish:1,lsb_releas:1,fast:1,open:1,predefin:1,size:1,given:1,xunicod:1,sheet:1,convent:1,gif:1,white:1,conveni:1,cite:1,forthcom:1,especi:1,copi:[0,1],bsubex:1,specifi:1,"short":1,enclos:1,than:1,png:1,wide:1,instanc:1,posit:1,zsh:1,browser:1,pre:1,unoconv:1,sai:1,nicer:1,pro:1,svnroot:1,ani:1,dash:1,zumbusch:1,mislead:1,engin:1,squar:1,destroi:1,moreov:1,note:[0,1],myeq2:1,take:1,includegraph:1,begin:1,sure:1,normal:1,track:1,fix_bibtex4publish:1,pair:1,icon:1,latex:[0,1],later:1,typeset:[0,1],preambl:1,main_myproj:1,viscou:1,show:1,scitool:1,bright:1,corner:1,unfinish:1,slot:1,onli:1,activ:1,analyz:1,microtyp:1,overwritten:1,variou:1,get:1,xcod:1,tailor:1,springer_collect:1,requir:1,reveal:1,tikz:1,cppcod:1,seldom:1,rst2pdf:1,paper:1,next1:1,where:1,summari:1,wiki:[0,1],"_sever":1,detect:1,xetex:1,label:1,enough:1,between:1,"import":1,inputenc:1,parent:1,screen:1,come:1,tug:1,img:1,tutori:1,mani:1,fix:1,among:1,acceler:1,color:1,overview:[0,1],inspir:1,period:1,pop:1,colon:1,typic:1,ultim:1,segfault:1,mark:1,structuredtext:1,encapusl:1,emphas:1,resolut:1,f90:1,f95:1,impati:1,former:1,those:1,"case":1,thesi:1,invok:1,advantag:1,ctrl:1,henc:1,destin:1,eras:1,ascii:[0,1],pdftk:1,develop:1,author:1,media:1,same:1,html:[0,1],document:[0,1],equat:1,nest:1,assist:1,extern:1,mycount:1,appropri:1,inconsist:1,macro:[0,1],markup:[0,1],ccq:1,sreen:1,without:1,kaar:1,venu:1,execut:1,documentclass:1,rest:[0,1],without_solut:1,flavor:1,hint:1,except:1,littl:1,blog:[0,1],treatment:1,exercis:[0,1],real:1,around:1,read:1,swig:1,nonnest:1,dark:1,grid:1,envir:1,world:1,mydict:1,whitespac:1,cdot:1,inted:1,integ:1,either:1,"_static":1,output:[0,1],fulfil:1,normalvec:1,thpack:1,palatino:1,shadowbox:1,constitut:1,definit:1,legal:1,ddt:1,subproblem:1,exit:1,refer:[0,1],power:1,inspect:1,tables2csv:1,fulli:1,regexp:1,src:1,split_html:1,stand:1,act:1,mytempl:1,dtodonot:1,myroutin:1,fundamental1:1,pagebreak:1,yyi:1,your:1,wikibook:1,log:1,her:1,area:1,haskel:1,start:1,lot:1,verbatim:[0,1],bundl:1,streamtub:1,diffus:1,blueish:1,untag:1,pull:1,possibl:1,"default":1,plaympeg:1,creol:1,externaldocu:1,xcolor:1,creat:1,certain:1,strongli:1,intro:1,decreas:1,file:[0,1],again:1,googl:1,valid:1,you:1,condens:1,sequenc:1,symbol:1,langtangen_et_al_2002:1,sidebartextcolor:1,includemedia:1,exerinfo:1,tmp_mako__filenam:1,unbalanc:1,backward:1,directori:1,descript:[0,1],potenti:1,cpp:1,escap:1,all:1,forget:1,illustr:1,dollar:1,"___sec2":1,follow:1,alt:1,external_movie_view:1,iconv:1,articl:1,program:[0,1],introduc:1,straightforward:1,fals:1,helvet:1,util:1,"1px":1,verb:1,mechan:1,texconv:1,veri:1,strang:1,unalt:1,nileshbans:1,list:[0,1],adjust:1,plain:[0,1],small:1,dxelatex:1,tex:[0,1],design:1,pass:1,further:1,what:[0,1],sub:1,section:1,netpbm:1,delet:1,version:1,method:1,full:1,hash:1,verbatim_text:1,sophist:1,behaviour:1,trunk:1,strong:1,modifi:1,valu:[0,1],search:[0,1],newlin:1,prior:1,amount:1,pick:1,action:1,narrow:1,via:1,depart:1,rightsidebar:1,filenam:1,href:1,html_theme:1,proceed:1,two:1,formul:1,taken:1,more:1,diamond:1,desir:1,ital:1,dnote:1,flag:1,stick:1,aris:1,known:1,shkumagai:1,none:1,valuabl:1,outlin:1,histori:1,paragraph:1,learn:1,rst2html:1,def:1,uncom:1,inline_tag_begin:1,dexternal_movie_view:1,accept:1,phrase:1,string:1,cours:1,csh:1,divid:1,rather:1,anoth:1,spreadsheet:1,snippet:1,csv:1,simpl:1,css:1,agogo:1,resourc:1,referenc:[0,1],variant:1,"_text":1,fignam:1,wave:1,associ:1,github:1,md2latex:1,footer:[0,1],confus:1,caus:1,testdoc:1,egg:1,help:1,devhelp:1,soon:1,scientist:1,through:1,myarr:1,paramet:1,style:1,roemer:1,ptext2tex:1,amsfont:1,gwiki:[0,1],might:1,fool:1,recip:1,good:1,"return":[0,1],sentenc:1,sphinxfix_localurl:1,petter:1,parenthesi:1,epsfig:1,troubleshoot:[0,1],easili:1,achiev:1,fpro:1,found:1,dir2:1,dir1:1,maketitl:1,sidebarbgcolor:1,hard:1,idea:[0,1],procedur:1,realli:1,heavi:1,beyond:1,"_part":1,publish:1,research:1,footnot:1,lineno:1,print:1,subsubsect:1,my_fil:1,advanc:1,pub:1,ref4:1,reason:1,base:1,put:1,teach:1,bash:1,launch:1,veloc:1,script:1,dpalatino:1,caption:1,perhap:1,fcod:1,ubuntuforum:1,major:1,feel:1,famou:1,misc:1,number:1,unovonv:1,smaller:[0,1],done:1,construct:1,blank:1,miss:[0,1],fanci:1,differ:[0,1],pandoc:[0,1],without_answ:1,cpp_an:1,interact:1,least:1,latexdiff:1,statement:1,natur:1,illeg:1,scheme:1,evinc:1,option:1,part:1,pars:[0,1],myclass:1,kind:1,ffmpeg:1,whenev:1,remov:[0,1],bibliographystyl:1,horizont:1,reus:1,store:1,sty:1,cleaner:1,comput:[0,1],packag:1,anslist:1,built:1,self:1,also:1,institution2:1,institution3:1,institution1:1,distribut:1,previou:1,reach:1,most:1,plai:1,exer:1,destruct:1,ext:1,clean:1,microsoft:1,think:1,sublist:1,diffpdf:1,session:1,particularli:1,font:1,fine:1,find:1,auctex:1,impact:1,mwlib:1,mjolnir:1,writer:1,solut:1,templat:1,smtplib:1,remedi:1,express:1,nativ:1,libreoffic:1,eq1:1,common:1,set:1,dump:1,creator:1,see:1,sed:1,close:1,someth:1,mybibtexfil:1,no_preprocess:1,subdir:1,experi:1,birkenfeld:1,altern:1,impressj:1,imagemagick:1,numer:1,javascript:1,subexercis:1,ipython:1,water:1,last:1,delimit:1,hyperlink:1,alon:1,"_part0001_mydoc":1,context:1,forgotten:1,pdf:1,whole:1,load:1,markdown:[0,1],simpli:1,point:1,header:[0,1],pycod:1,linux:1,throughout:1,becom:1,java:1,devic:1,due:1,empti:1,newcommands_replac:1,eart2moon_sol:1,strategi:1,invis:1,imag:1,remark:1,epytext:1,understand:1,demand:1,look:1,bluish2:1,formatt:[0,1],"while":1,smart:1,abov:1,error:1,subsitut:1,vlinux:1,pack:1,subsect:1,propag:1,html_admon:1,readi:1,itself:1,rid:1,minim:1,shorter:1,archiv:1,myslid:1,esubex:1,alert:1,user:1,cwiki:1,recent:1,lower:1,task:1,entri:1,elev:1,propos:1,explan:1,langtangen:1,restructuredtext:[0,1],shortcut:1,informat:1,theorem:[0,1],input:1,subroutin:1,format:[0,1],big:1,bib:1,backquot:1,table2:1,table3:1,semi:1,brace:1,xxdiff:1,resolv:1,"_part0002_mydoc":1,popular:1,ignorn:1,encount:1,sketch:1,often:1,simplifi:1,creation:1,some:1,back:1,understood:1,scale:1,montag:1,per:1,substitut:1,mathemat:[0,1],larg:1,retro:1,prog:1,object:1,run:1,zzz:1,newcommand_replac:1,step:[0,1],qthelp:1,idx:1,materi:1,idl:1,incompress:1,langtangen_2003a:1,block:[0,1],file3:1,file2:1,file1:1,doubl:1,emphasi:1,file4:1,within:1,ensur:1,perl:1,occupi:1,inclus:1,mkd:1,span:1,question:1,nosidebar:1,textual:1,custom:1,guess_encod:1,subst:1,includ:1,suit:1,myfunc:1,properli:1,link:1,translat:1,newer:1,line:[0,1],listtyp:1,concaten:1,latex_preambl:1,utf:1,consist:1,inline_tag:1,apricot:1,access:1,someus:1,"export":1,similar:1,knob_left:1,repres:1,incomplet:1,home:1,curl:1,titl:1,invalid:1,bibfil:1,bracket:1,prev1:1,newcommands_keep:1,nice:1,mathpazo:1,colored_table_row:1,svn:1,rst2latex:1,bsummari:1,depth:1,far:1,code:[0,1],partial:1,totem:1,rtf:1,makeidx:1,moon:1,refs3:1,refs2:1,refs1:1,compact:1,cython:1,showthread:1,elsewher:1,send:1,becam:1,sens:1,fenics_minim:1,docoment:1,titlepag:1,makotempl:1,volum:1,untouch:1,relev:1,tri:1,"20435c":1,button:1,ryan:1,"try":1,impli:1,exted:1,cfg:1,odt:1,jump:1,video:1,haiku:1,download:1,click:1,index:[0,1],femdeq:1,compar:1,resembl:1,multimedia:1,cell:1,experiment:1,remove_inline_com:1,mathjax:1,tveito:1,deduc:1,whatev:1,vibrat:1,bibitem:1,matplotlib:1,html_fenic:1,bodi:1,let:1,dmovie15:1,ubuntu:[0,1],vertic:1,sinc:1,convert:1,convers:1,larger:1,chang:1,problemat:1,chanc:1,firefox:1,appli:1,colors1:1,apt:1,cloud:1,from:[0,1],live:1,mydir:1,next:1,websit:1,few:1,postprocess:1,sort:1,slim:1,comparison:1,trail:1,langtangen_pedersen_2002:1,retriev:1,annoi:1,column:1,obvious:1,meet:1,proof:1,control:1,quickstart:1,process:1,sudo:1,blue_section_head:1,tag:[0,1],doconce_install_al:1,tarbal:1,surfac:1,subdirectori:1,instead:1,sin:1,yellowish:1,frac:1,stop:1,mypack:1,earth2moon:1,exemplifi:1,keep_pygments_html_bg:1,colors2:1,essenti:1,light:1,counter:1,correspond:1,element:1,issu:1,epstopdf:1,allow:1,dmint:1,elif:1,movi:[0,1],move:1,comma:1,libav:1,myprog:1,outer:1,latex_head:1,chosen:1,therefor:1,docx:1,crash:1,python:1,handi:1,dat:1,mention:1,textopc:1,somewher:1,inline_tag_end:1,edit:1,wdiff:1,uvec:1,slide:[0,1],mode:1,mystyl:1,"10pt":1,pygment:1,subset:1,intellig:1,subsec:1,our:1,special:[0,1],out:1,variabl:[0,1],matrix:1,esummari:1,sandbox:1,texliv:1,suitabl:1,rel:1,ref:1,math:1,statist:1,insid:1,manipul:1,standalon:1,dictionari:1,pedersen:1,indent:1,could:1,ask:1,movie15:1,keep:1,length:1,outsid:1,navier:1,geometri:1,cyberspac:1,softwar:1,manuscript:1,blogger:1,texshop:1,date:1,"long":1,mkdir:1,system:1,messag:1,termin:1,siam:1,"final":1,shell:1,bhint:1,bblock:1,cyb:1,rst:1,newtheorem:1,exactli:1,myfram:1,structur:1,charact:1,steer:1,viewer:1,explicit:1,have:1,tabl:[0,1],need:1,turn:1,border:1,table4:1,minted_python:1,preced:1,which:1,divers:1,singl:1,unless:1,preliminari:1,who:1,ooxml:1,awl:1,mplayer:1,twitter_bootstrap:1,segment:1,"class":1,epub:1,"_build":1,todonot:1,latin1:1,url:1,hardcod:1,face:1,pipe:1,bibtex:1,determin:1,ubuntu_vers:1,fact:1,smpeg:1,text:[0,1],skip_inline_com:1,knob_forward:1,blognam:1,graybox1:1,graybox2:1,graybox3:1,thicker:1,emac:[0,1],titlesec:1,html_templat:1,dispers:1,jal:1,"_mydoc":1,suppos:1,conclus:1,local:1,ksh:1,meant:1,mythem:1,contribut:1,familiar:1,autom:1,table_x:1,pressbook:1,enabl:1,theorem_fundamental1:1,ewarn:1,grai:1,blogspot:1,integr:1,contain:1,typset:1,end1:1,frame:1,"_doconce_debug":1,incoveni:1,pngmath:1,correctli:1,boundari:1,written:1,hyperbaseurl:1,neither:1,email:1,kei:1,job:1,entir:1,exclam:1,embed:1,addit:1,hyperref:1,nabla:1,equal:1,thereaft:1,etc:1,eta:1,html_slide_them:1,html5:[0,1],comment:[0,1],cxx:1,guidelin:1,distinguish:1,respect:1,ifthen:1,quit:1,mjpegtool:1,blueish2:1,m2html:1,json:1,treat:1,curli:1,both:1,split_:1,bremark:1,media9:1,togeth:1,graphicx:1,present:1,multi:1,eeqa:1,vimeo:1,align:1,defin:[0,1],customiz:1,almost:1,demo:[0,1],texttt:1,site:1,change_encod:1,simulate_and_plot:1,revis:1,scienc:1,satisfi:1,cross:[0,1],handl:1,html_pyramid:1,template_vagr:1,mydoc:1,inc:1,difficult:1,http:1,ref1:1,expans:1,ref3:1,ref2:1,ref5:1,effect:1,a4pap:1,redcloud:1,logfil:1,php:1,expand:1,off:1,center:1,openofficeword:1,nevertheless:1,well:1,difflib:1,autoplai:1,exampl:[0,1],command:1,english:1,undefin:1,usual:1,distanc:1,less:1,obtain:1,tcl:1,fenic:1,web:1,makefil:[0,1],add:1,other:[0,1],bibliographi:[0,1],match:1,dextra_sect:1,css3:1,rememb:1,hpl:1,piec:[0,1],realiz:1,know:1,tick:1,testm:1,insert:1,resid:1,like:1,success:1,unord:1,necessari:1,dlatex_head:1,page:[0,1],"11px":1,underscror:1,captur:1,suppli:1,python_anst:1,scipy_lectur:1,latex_print:1,proper:1,guarante:1,lead:1,avoid:1,yellowbox:1,leav:1,newfil:1,speak:1,mathmpl:1,investig:1,journal:1,usag:1,host:1,encourav:1,although:1,simpler:1,about:1,actual:1,rst2:1,linenumb:1,powerpoint:1,own:1,amsmath:1,automat:1,bsol:1,merg:1,citat:1,pictur:1,trigger:1,"var":1,"function":[0,1],multigrid:1,unexpect:1,ean:1,overflow:1,inlin:[0,1],bug:1,count:1,made:1,wise:1,wish:1,googlecod:1,displai:1,troubl:1,below:1,limit:1,otherwis:1,problem:[0,1],"int":1,dure:1,tmp_preprocess__filenam:1,enotic:1,novemb:1,implement:1,pip:1,sphinxjp:1,probabl:1,detail:1,book:1,bool:1,futur:1,branch:1,varieti:1,fontspec:1,repeat:1,shown:1,no_mako:1,debian:[0,1],sphinx:[0,1],eof:1,scientif:1,rule:1,portion:1,openoffic:1,f77:1},objtypes:{},titles:["Doconce
Manual","Doconce
Description"],objnames:{},filenames:["index","manual"]})
+Search.setIndex({objects:{},terms:{mydoc2:1,linebreak:1,yellow:1,four:1,fig2:1,fig3:1,fig1:1,consider:1,spellcheck:1,ecollin:1,usepackag:1,matlab:1,under:1,preprocess:[0,1],yourdoc:1,everi:1,wrapper_tech:1,"void":1,rise:1,theorem_count:1,affect:1,pygments_html_lineno:1,disturb:1,upload:1,vector:1,math:1,darkgrai:1,relsiz:1,dirnam:1,direct:1,consequ:1,second:1,esol:1,blue:1,mpeg:1,extra_sect:1,"new":1,net:1,never:1,here:1,"const":1,python_an:1,interpret:1,forum:1,ptex2tex:1,precis:1,loop:1,studi:1,brought:1,unix:1,org:1,outro:1,txt:1,shcod:1,describ:1,would:1,includemovi:1,doconc:[0,1],call:1,typo:1,recommend:1,calc:1,type:1,pdfcrop:1,relat:1,footerbgcolor:1,notic:1,warn:1,mwk:1,rootdir:1,si2uchh3qim:1,automake_sphinx:1,must:1,springer:1,word:1,setup:1,work:1,split_rst:1,root:1,overrid:1,give:1,da6pap:1,somefil:1,caution:1,want:1,attract:1,end:1,quot:1,ordinari:1,vagrant:1,how:1,answer:1,perspect:1,updat:1,recogn:1,after:1,befor:1,wrong:1,demonstr:1,basicstrap:1,attempt:1,pdfnup:1,bootstrap:1,mwiki:1,neglect:1,myeq1:1,maintain:1,environ:[0,1],eblock:1,enter:1,order:1,srclib:1,deck:1,over:1,becaus:1,jpeg:1,keyboard:1,flexibl:1,vari:1,myfil:1,fit:1,setspac:1,better:1,offic:1,fig:1,comprehens:1,html_style:1,easier:1,miiton:1,them:1,var1:1,thei:1,safe:1,"break":1,yourself:1,choic:1,sphinxext:1,each:1,debug:[0,1],side:1,mean:1,pdflatex:[0,1],laboratori:1,logg:1,extract:1,goe:1,content:[0,1],rewrit:1,fairli:1,sphinx_dir:1,reader:1,forth:1,linear:1,navig:1,situat:1,standard:1,acrobat:1,reformul:1,bwarn:1,argument:[0,1],filter:1,iso:1,examples_as_exercis:1,onto:1,no_pygments_html:1,"__theorem":1,rang:1,html_theme_opt:1,render:1,independ:1,biomed:1,restrict:1,instruct:1,alreadi:1,"__abstract":1,primari:1,top:1,sometim:1,mercuri:1,underlin:1,master:1,too:1,similarli:1,toc:1,consol:1,tool:1,xkeyval:1,somewhat:1,knob:1,simula:1,solvin:1,charcter:1,past:1,target:1,keyword:1,provid:1,tree:1,usepack:1,project:[0,1],doonc:1,"5mm":1,admonit:[0,1],fashion:1,dvar1:1,modern:1,raw:1,pylon:1,seen:1,mint:1,minu:1,minted_cpp:1,latter:1,even:1,though:1,pdiff:1,ebook:1,regular:1,letter:1,choos:1,style_vagr:1,tradit:1,don:1,doc:1,flow:1,doe:1,dummi:1,abbrev:1,declar:1,unchang:1,winther:1,random:1,pygments_html_styl:1,syntax:1,mediawiki:1,indentend:1,theme_dir:1,involv:1,layout:1,explain:1,configur:1,theme:1,rich:1,shoutwiki:1,agni:1,watch:1,fluid:1,encourg:1,cloud_spthem:1,makeindex:1,report:1,keyword2:1,keyword1:1,youtub:1,briefer:1,emb:1,"public":1,ban:1,respond:1,kolmogorov:1,pdftool:1,result:1,fail:1,best:1,awar:1,databas:1,wikipedia:1,figur:[0,1],simplest:1,awai:1,approach:1,accord:1,slides_beam:1,extend:1,extens:1,lazi:1,preprocessor:1,extent:1,toler:1,han:1,howev:1,subitem:1,cod:1,docbook:1,seri:1,com:1,mardal:1,dbook:1,height:1,stylefil:1,documentstyl:1,path:1,diff:1,guid:1,assum:1,summar:1,duplic:1,union:1,numpi:1,three:1,been:1,much:1,sphinxdir:1,basic:[0,1],futur:1,quickli:1,life:1,deeper:1,spit:1,xxy:1,xxx:1,anywher:1,els:1,emploi:1,ugli:1,ident:1,subentri:1,gnu:1,servic:1,properti:1,sourceforg:1,aim:1,dept:1,aid:1,anchor:1,pyramid:1,coher:1,conv:1,a6pap:1,conf:1,sever:1,mako:[0,1],disabl:1,perform:1,suggest:1,make:1,complex:1,split:[0,1],texinfo:1,complet:1,a2p:1,slides_html:1,mytext:1,hand:1,bibliograph:1,norwegian:1,pngmath_dvipng_arg:1,tune:1,moondist:1,redefin:1,kept:1,undesir:1,thi:1,endif:1,everyth:1,giftran:1,left:1,identifi:1,just:1,rst2odt:1,xelatex:[0,1],human:1,ifdef:1,kdiff3:1,yet:1,languag:[0,1],easi:1,mix:1,interfer:1,fortran:1,cp2texmf:1,save:1,explanatori:1,gave:1,mayb:1,boldfac:1,fromto:1,background:1,shadow:1,wrapfig:1,measur:1,amon:1,specif:1,arbitrari:1,manual:[0,1],docutil:1,www:1,right:1,old:1,intern:1,toctre:1,successfulli:1,total:1,collect:1,univ:1,core:1,plu:1,bold:1,fancyvrb:1,repositori:1,post:[0,1],chapter:1,slightli:1,surround:1,unfortun:1,algn:1,"__proof":1,produc:1,ppa:1,"float":1,encod:1,fancybox:1,down:1,wrap:1,accordingli:1,git:1,perldoc:1,suffici:1,support:1,transform:1,why:1,avail:1,width:1,wordpress:1,editor:1,analysi:1,head:1,satisfactorili:1,form:1,offer:1,solar:1,"true":1,rerun:1,featur:[0,1],classic:1,request:1,"abstract":1,ephas:1,postscript:1,exist:1,check:1,assembl:1,somenam:1,tkdiff:1,eremark:1,when:1,test:1,diffpack:1,matur:1,notif:1,intend:1,asterisk:1,consid:1,occasion:1,stoke:1,bitbucket:1,longer:1,bullet:1,phone:1,ignor:1,maxdepth:1,time:1,beamer:[0,1],nxn:1,concept:1,particular:1,row:1,middl:1,depend:[0,1],unnumb:1,flask:1,texmf:1,proj:1,sourc:[0,1],xpro:1,brows:1,seemingli:1,level:1,did:1,relbarbgcolor:1,iter:1,item:1,preprocesor:1,combine_imag:1,team:1,quick:[0,1],sidebarlinkcolor:1,round:1,dir:1,sign:1,dmath:1,appear:1,anywai:1,current:1,rst2xml:1,meld:1,xml:1,autogener:1,gener:[0,1],disclaim:[0,1],modif:1,address:1,locat:1,along:1,box:1,shift:1,trial:1,behav:1,myvar:1,slidecel:1,extra:1,tweak:[0,1],modul:[0,1],ipi:1,prefer:1,backtick:1,visibl:1,instal:[0,1],should:1,regex:1,dvipdf:1,univers:1,helvetica:1,todai:1,subvers:1,stylesheet:1,criteria:1,checkout:1,share:1,newcommand:[0,1],visual:1,appendix:1,indic:[0,1],examin:1,easiest:1,dhelvetica:1,slogan:1,uniqu:1,impel:1,can:1,cal:1,purpos:1,ehint:1,claim:1,encapsul:1,bloodish:1,backslash:1,topic:1,abort:1,occur:1,alwai:1,differenti:1,multipl:1,oslo:1,no_abort:1,write:[0,1],pure:1,tile:1,ispel:1,map:1,clone:1,codetermin:1,mac:1,mai:1,underscor:1,data:1,man:1,mdframe:1,favorit:1,inform:1,"switch":1,cannot:1,combin:1,ssh:1,epydoc:1,boldface_:1,"_part0000_mydoc":1,equip:1,still:1,mainli:1,dynam:1,entiti:1,group:1,passag:1,platform:1,window:1,doconce_head:1,main:1,non:1,recal:1,matcher:1,initi:1,half:1,now:1,discuss:1,nor:1,name:1,config:1,separ:1,mydoc_html_file_collect:1,admon:1,compil:1,f2f2f2:1,replac:1,individu:1,continu:1,backport:1,year:1,happen:1,reportlab:1,space:1,bnotic:1,sespecif:1,formula:1,md2html:1,correct:1,headlin:1,fontsiz:1,mako_strict_undefin:1,institut:1,care:1,"__a":1,wai:1,modest:1,thing:1,place:1,view:1,nicknam:1,imposs:1,frequent:1,first:1,origin:1,directli:1,carri:1,onc:1,arrai:1,bluish:1,lsb_releas:1,fast:1,open:1,predefin:1,size:1,given:1,xunicod:1,sheet:1,convent:1,gif:1,white:1,conveni:1,cite:1,forthcom:1,especi:1,copi:[0,1],bsubex:1,specifi:1,"short":1,enclos:1,than:1,png:1,wide:1,instanc:1,posit:1,zsh:1,browser:1,pre:1,unoconv:1,sai:1,nicer:1,pro:1,svnroot:1,ani:1,dash:1,zumbusch:1,mislead:1,engin:1,squar:1,destroi:1,moreov:1,note:[0,1],myeq2:1,take:1,includegraph:1,begin:1,sure:1,normal:1,track:1,fix_bibtex4publish:1,pair:1,icon:1,latex:[0,1],later:1,typeset:[0,1],preambl:1,main_myproj:1,viscou:1,show:1,scitool:1,bright:1,corner:1,unfinish:1,slot:1,onli:1,activ:1,analyz:1,microtyp:1,overwritten:1,variou:1,get:1,xcod:1,tailor:1,springer_collect:1,requir:1,reveal:1,tikz:1,cppcod:1,seldom:1,rst2pdf:1,paper:1,next1:1,where:1,summari:1,wiki:[0,1],"_sever":1,detect:1,xetex:1,label:1,enough:1,between:1,"import":1,inputenc:1,parent:1,screen:1,come:1,tug:1,img:1,tutori:1,mani:1,fix:1,among:1,acceler:1,color:1,overview:[0,1],inspir:1,period:1,pop:1,colon:1,typic:1,ultim:1,segfault:1,mark:1,structuredtext:1,encapusl:1,emphas:1,resolut:1,f90:1,f95:1,impati:1,former:1,those:1,"case":1,thesi:1,invok:1,advantag:1,ctrl:1,henc:1,destin:1,eras:1,ascii:[0,1],pdftk:1,develop:1,author:1,media:1,same:1,html:[0,1],document:[0,1],equat:1,nest:1,assist:1,extern:1,mycount:1,appropri:1,inconsist:1,macro:[0,1],markup:[0,1],ccq:1,sreen:1,without:1,kaar:1,venu:1,execut:1,documentclass:1,rest:[0,1],without_solut:1,flavor:1,hint:1,except:1,littl:1,blog:[0,1],treatment:1,exercis:[0,1],real:1,around:1,read:1,swig:1,nonnest:1,dark:1,grid:1,envir:1,world:1,mydict:1,whitespac:1,cdot:1,inted:1,integ:1,either:1,"_static":1,output:[0,1],fulfil:1,thpack:1,palatino:1,shadowbox:1,constitut:1,definit:1,legal:1,moon:1,subproblem:1,exit:1,refer:[0,1],power:1,inspect:1,tables2csv:1,fulli:1,regexp:1,src:1,split_html:1,stand:1,act:1,mytempl:1,dtodonot:1,myroutin:1,fundamental1:1,pagebreak:1,yyi:1,your:1,wikibook:1,log:1,her:1,area:1,haskel:1,start:1,lot:1,verbatim:[0,1],bundl:1,jun:1,streamtub:1,diffus:1,blueish:1,untag:1,pull:1,possibl:1,"default":1,plaympeg:1,creol:1,externaldocu:1,xcolor:1,creat:1,certain:1,strongli:1,intro:1,decreas:1,file:[0,1],again:1,googl:1,valid:1,you:1,condens:1,sequenc:1,symbol:1,langtangen_et_al_2002:1,sidebartextcolor:1,includemedia:1,exerinfo:1,tmp_mako__filenam:1,unbalanc:1,backward:1,directori:1,descript:[0,1],lbrack:1,potenti:1,cpp:1,escap:1,all:1,forget:1,illustr:1,dollar:1,"___sec2":1,follow:1,alt:1,external_movie_view:1,iconv:1,articl:1,program:[0,1],introduc:1,straightforward:1,fals:1,helvet:1,util:1,"1px":1,verb:1,mechan:1,texconv:1,veri:1,strang:1,unalt:1,nileshbans:1,list:[0,1],adjust:1,plain:[0,1],small:1,dxelatex:1,tex:[0,1],design:1,pass:1,further:1,what:[0,1],sub:1,section:1,netpbm:1,delet:1,version:1,method:1,full:1,hash:1,verbatim_text:1,misspel:1,sophist:1,behaviour:1,trunk:1,strong:1,modifi:1,valu:[0,1],search:[0,1],newlin:1,prior:1,amount:1,pick:1,action:1,narrow:1,via:1,depart:1,rightsidebar:1,filenam:1,href:1,html_theme:1,proceed:1,two:1,formul:1,taken:1,more:1,diamond:1,desir:1,ital:1,dnote:1,flag:1,stick:1,aris:1,known:1,shkumagai:1,none:1,valuabl:1,outlin:1,histori:1,paragraph:1,learn:1,rst2html:1,def:1,uncom:1,inline_tag_begin:1,dexternal_movie_view:1,accept:1,phrase:1,string:1,cours:1,csh:1,divid:1,rather:1,anoth:1,spreadsheet:1,snippet:1,csv:1,simpl:1,css:1,agogo:1,resourc:1,referenc:[0,1],variant:1,"_text":1,fignam:1,wave:1,associ:1,github:1,md2latex:1,footer:[0,1],confus:1,caus:1,testdoc:1,egg:1,help:1,devhelp:1,soon:1,scientist:1,through:1,myarr:1,paramet:1,style:1,roemer:1,ptext2tex:1,amsfont:1,gwiki:[0,1],might:1,fool:1,recip:1,good:1,"return":[0,1],sentenc:1,sphinxfix_localurl:1,petter:1,parenthesi:1,epsfig:1,troubleshoot:[0,1],easili:1,achiev:1,fpro:1,found:1,dir2:1,dir1:1,maketitl:1,sidebarbgcolor:1,hard:1,idea:[0,1],procedur:1,realli:1,heavi:1,beyond:1,"_part":1,publish:1,research:1,footnot:1,lineno:1,print:1,subsubsect:1,my_fil:1,advanc:1,pub:1,ref4:1,reason:1,base:1,put:1,teach:1,bash:1,launch:1,veloc:1,script:1,dpalatino:1,caption:1,perhap:1,fcod:1,ubuntuforum:1,major:1,feel:1,famou:1,misc:1,number:1,unovonv:1,smaller:[0,1],done:1,construct:1,blank:1,miss:[0,1],fanci:1,differ:[0,1],pandoc:[0,1],without_answ:1,cpp_an:1,interact:1,least:1,latexdiff:1,statement:1,cfg:1,illeg:1,scheme:1,evinc:1,option:1,part:1,pars:[0,1],myclass:1,kind:1,ffmpeg:1,whenev:1,remov:[0,1],bibliographystyl:1,horizont:1,reus:1,store:1,sty:1,cleaner:1,comput:[0,1],packag:1,anslist:1,built:1,self:1,also:1,institution2:1,institution3:1,institution1:1,distribut:1,csv2tabl:1,previou:1,reach:1,most:1,plai:1,exer:1,destruct:1,ext:1,clean:1,microsoft:1,think:1,sublist:1,diffpdf:1,session:1,particularli:1,font:1,fine:1,find:1,auctex:1,impact:1,mwlib:1,mjolnir:1,writer:1,solut:1,templat:1,smtplib:1,remedi:1,express:1,nativ:1,libreoffic:1,eq1:1,common:1,set:1,dump:1,creator:1,see:1,sed:1,close:1,someth:1,mybibtexfil:1,no_preprocess:1,subdir:1,experi:1,birkenfeld:1,altern:1,impressj:1,imagemagick:1,numer:1,javascript:1,subexercis:1,ipython:1,water:1,last:1,delimit:1,hyperlink:1,alon:1,"_part0001_mydoc":1,context:1,forgotten:1,pdf:1,whole:1,load:1,markdown:[0,1],simpli:1,point:1,header:[0,1],pycod:1,linux:1,mistak:1,throughout:1,becom:1,java:1,devic:1,due:1,empti:1,newcommands_replac:1,eart2moon_sol:1,strategi:1,invis:1,imag:1,remark:1,epytext:1,understand:1,demand:1,look:1,bluish2:1,formatt:[0,1],"while":1,smart:1,abov:1,error:1,subsitut:1,vlinux:1,pack:1,subsect:1,propag:1,html_admon:1,readi:1,itself:1,rid:1,minim:1,shorter:1,archiv:1,myslid:1,esubex:1,alert:1,user:1,cwiki:1,recent:1,lower:1,task:1,entri:1,elev:1,propos:1,explan:1,langtangen:1,restructuredtext:[0,1],shortcut:1,informat:1,theorem:[0,1],input:1,subroutin:1,format:[0,1],big:1,bib:1,backquot:1,table2:1,table3:1,semi:1,brace:1,xxdiff:1,resolv:1,"_part0002_mydoc":1,popular:1,ignorn:1,encount:1,sketch:1,often:1,simplifi:1,creation:1,some:1,back:1,understood:1,scale:1,montag:1,per:1,substitut:1,mathemat:[0,1],larg:1,retro:1,prog:1,object:1,run:1,zzz:1,newcommand_replac:1,step:[0,1],qthelp:1,idx:1,materi:1,idl:1,incompress:1,langtangen_2003a:1,block:[0,1],file3:1,file2:1,file1:1,doubl:1,emphasi:1,file4:1,within:1,ensur:1,perl:1,occupi:1,inclus:1,mkd:1,span:1,question:1,nosidebar:1,textual:1,custom:1,guess_encod:1,subst:1,includ:1,suit:1,myfunc:1,properli:1,link:1,translat:1,newer:1,delta:1,line:[0,1],listtyp:1,concaten:1,latex_preambl:1,utf:1,consist:1,inline_tag:1,apricot:1,access:1,someus:1,"export":1,similar:1,knob_left:1,repres:1,incomplet:1,home:1,curl:1,titl:1,invalid:1,bibfil:1,bracket:1,prev1:1,newcommands_keep:1,nice:1,mathpazo:1,colored_table_row:1,svn:1,rst2latex:1,bsummari:1,depth:1,far:1,code:[0,1],partial:1,totem:1,rtf:1,makeidx:1,refs3:1,refs2:1,refs1:1,compact:1,cython:1,showthread:1,elsewher:1,send:1,becam:1,sens:1,fenics_minim:1,docoment:1,titlepag:1,makotempl:1,volum:1,untouch:1,relev:1,tri:1,"20435c":1,button:1,ryan:1,"try":1,impli:1,exted:1,fortun:1,natur:1,odt:1,jump:1,video:1,haiku:1,download:1,click:1,index:[0,1],femdeq:1,compar:1,resembl:1,multimedia:1,cell:1,experiment:1,remove_inline_com:1,mathjax:1,tveito:1,deduc:1,whatev:1,vibrat:1,bibitem:1,matplotlib:1,html_fenic:1,bodi:1,let:1,dmovie15:1,ubuntu:[0,1],vertic:1,sinc:1,convert:1,convers:1,larger:1,chang:1,problemat:1,chanc:1,firefox:1,appli:1,colors1:1,apt:1,cloud:1,from:[0,1],tmp_missing_:1,live:1,mydir:1,next:1,websit:1,few:1,postprocess:1,sort:1,slim:1,comparison:1,trail:1,langtangen_pedersen_2002:1,retriev:1,annoi:1,column:1,obvious:1,meet:1,proof:1,control:1,quickstart:1,process:1,sudo:1,blue_section_head:1,tag:[0,1],doconce_install_al:1,tarbal:1,surfac:1,subdirectori:1,instead:1,sin:1,yellowish:1,frac:1,stop:1,mypack:1,earth2moon:1,exemplifi:1,keep_pygments_html_bg:1,colors2:1,essenti:1,light:1,counter:1,correspond:1,element:1,issu:1,epstopdf:1,allow:1,dmint:1,elif:1,movi:[0,1],move:1,comma:1,libav:1,myprog:1,outer:1,latex_head:1,chosen:1,therefor:1,docx:1,crash:1,python:1,handi:1,dat:1,mention:1,textopc:1,somewher:1,inline_tag_end:1,edit:1,wdiff:1,slide:[0,1],mode:1,mystyl:1,"10pt":1,pygment:1,subset:1,intellig:1,meta:1,subsec:1,our:1,special:[0,1],out:1,variabl:[0,1],matrix:1,esummari:1,sandbox:1,texliv:1,suitabl:1,rel:1,ref:1,red:1,statist:1,insid:1,manipul:1,standalon:1,dictionari:1,pedersen:1,indent:1,could:1,ask:1,movie15:1,keep:1,length:1,outsid:1,navier:1,geometri:1,cyberspac:1,softwar:1,manuscript:1,blogger:1,rbrack:1,texshop:1,date:1,"long":1,mkdir:1,system:1,messag:1,termin:1,siam:1,"final":1,shell:1,bhint:1,bblock:1,cyb:1,rst:1,newtheorem:1,exactli:1,myfram:1,structur:1,charact:1,steer:1,viewer:1,explicit:1,have:1,tabl:[0,1],need:1,turn:1,border:1,table4:1,minted_python:1,preced:1,which:1,divers:1,singl:1,unless:1,preliminari:1,who:1,ooxml:1,awl:1,mplayer:1,twitter_bootstrap:1,segment:1,"class":1,epub:1,"_build":1,todonot:1,latin1:1,url:1,hardcod:1,face:1,pipe:1,bibtex:1,determin:1,ubuntu_vers:1,superscript:1,fact:1,smpeg:1,text:[0,1],skip_inline_com:1,knob_forward:1,blognam:1,graybox1:1,graybox2:1,graybox3:1,thicker:1,emac:[0,1],titlesec:1,html_templat:1,dispers:1,jal:1,"_mydoc":1,suppos:1,conclus:1,local:1,ksh:1,meant:1,mythem:1,contribut:1,familiar:1,autom:1,pressbook:1,enabl:1,bisect:1,theorem_fundamental1:1,ewarn:1,grai:1,blogspot:1,integr:1,contain:1,typset:1,end1:1,frame:1,"_doconce_debug":1,incoveni:1,pngmath:1,correctli:1,boundari:1,written:1,hyperbaseurl:1,neither:1,email:1,kei:1,job:1,entir:1,exclam:1,embed:1,addit:1,hyperref:1,nabla:1,equal:1,thereaft:1,etc:1,eta:1,html_slide_them:1,html5:[0,1],comment:[0,1],cxx:1,guidelin:1,distinguish:1,respect:1,ifthen:1,x_y:1,quit:1,mjpegtool:1,blueish2:1,m2html:1,json:1,treat:1,curli:1,both:1,split_:1,bremark:1,media9:1,togeth:1,graphicx:1,present:1,multi:1,vimeo:1,align:1,defin:[0,1],customiz:1,almost:1,demo:[0,1],texttt:1,site:1,change_encod:1,simulate_and_plot:1,revis:1,scienc:1,satisfi:1,cross:[0,1],handl:1,html_pyramid:1,template_vagr:1,mydoc:1,inc:1,difficult:1,http:1,ref1:1,expans:1,ref3:1,ref2:1,ref5:1,effect:1,a4pap:1,redcloud:1,logfil:1,php:1,expand:1,off:1,center:1,openofficeword:1,nevertheless:1,well:1,difflib:1,autoplai:1,exampl:[0,1],command:1,english:1,undefin:1,usual:1,distanc:1,less:1,obtain:1,tcl:1,fenic:1,web:1,makefil:[0,1],add:1,other:[0,1],bibliographi:[0,1],match:1,dextra_sect:1,css3:1,rememb:1,hpl:1,piec:[0,1],realiz:1,know:1,tick:1,testm:1,insert:1,resid:1,like:1,success:1,unord:1,necessari:1,dlatex_head:1,page:[0,1],"11px":1,underscror:1,captur:1,suppli:1,python_anst:1,scipy_lectur:1,latex_print:1,proper:1,guarante:1,tmp:1,lead:1,avoid:1,yellowbox:1,leav:1,newfil:1,speak:1,mathmpl:1,investig:1,journal:1,usag:1,host:1,encourav:1,although:1,simpler:1,about:1,actual:1,rst2:1,linenumb:1,powerpoint:1,own:1,amsmath:1,automat:1,bsol:1,merg:1,citat:1,pictur:1,trigger:1,"var":1,"function":[0,1],multigrid:1,unexpect:1,ean:1,overflow:1,inlin:[0,1],bug:1,count:1,made:1,wise:1,wish:1,googlecod:1,displai:1,troubl:1,below:1,limit:1,otherwis:1,problem:[0,1],"int":1,dure:1,tmp_preprocess__filenam:1,enotic:1,novemb:1,implement:1,pip:1,sphinxjp:1,probabl:1,detail:1,book:1,bool:1,table_x:1,branch:1,varieti:1,fontspec:1,repeat:1,shown:1,no_mako:1,debian:[0,1],sphinx:[0,1],eof:1,scientif:1,rule:1,portion:1,openoffic:1,f77:1},objtypes:{},titles:["Doconce
Manual","Doconce
Description"],objnames:{},filenames:["index","manual"]})
=======================================
--- /doc/demos/manual/index.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/index.html Fri Jun 28 09:22:02 2013
@@ -41,7 +41,6 @@
<a href="manual.cwiki">Creole wiki</a>,
<a href="manual.mwiki">MediaWiki</a>,
<a href="manual.md">Markdown</a> (Pandoc extended version),
-<a href="manual.st">Structured Text</a>,
<a href="manual.epytext">Epytext</a>,
and maybe the most important format of all:
<a href="manual.txt">plain untagged ASCII text</a>.
=======================================
--- /doc/demos/manual/manual.cwiki Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.cwiki Fri Jun 28 09:22:02 2013
@@ -1,7 +1,7 @@
#summary Doconce Description
<wiki:toc max_depth="2" />
By **Hans Petter Langtangen**
-=== May 29, 2013 ===
+=== Jun 28, 2013 ===
<wiki:comment> lines beginning with # are doconce comment lines
</wiki:comment>
<wiki:comment> (documents can also have mako comment lines) </wiki:comment>
@@ -519,7 +519,7 @@
Transformation of a Doconce document {{{mydoc.do.txt}}} to various other
-formats applies the script {{{doconce format}}}:
+formats apply the script {{{doconce format}}}:
{{{
Terminal> doconce format format mydoc.do.txt
}}}
@@ -1988,7 +1988,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with {{{===}}} heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in {{{html}}} output such that search engines can make use of the them.
== Bibliography ==
@@ -2154,6 +2158,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes {{{|}}} can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+{{{
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+}}}
+
Note that not all formats offer alignment of heading or entries
in tables ({{{rst}}} and {{{sphinx}}} are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2165,6 +2182,33 @@
makes Doconce dump each table to CSV format in a file {{{table_X.csv}}},
where {{{X}}} is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+
+Data in CSV format can be transformed to Doconce table format
+by the {{{doconce csv2table}}} utility:
+
+{{{
+Terminal> doconce csv2table somefile.csv > table.do.txt
+}}}
+This is a quick way of writing tables. For example, we can
+write a text file {{{tmp.csv}}} with
+
+{{{
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+}}}
+Running {{{doconce csv2table tmp.csv}}} creates the table
+
+{{{
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+}}}
== Exercises, Problems, Projects, and Examples ==
@@ -2566,14 +2610,6 @@
\end{align}
!et
}}}
-Here is the result:
-
-{{{
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. label{myeq2}
-\end{align}
-}}}
The support of LaTeX mathematics varies among the formats:
@@ -2651,58 +2687,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-//Example.// Suppose we have the following commands in
-{{{newcommand_replace.tex}}}:
-
-{{{
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-}}}
-
-and these in {{{newcommands_keep.tex}}}:
-
-{{{
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-}}}
-
-The LaTeX block
-{{{
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-}}}
-will then be rendered to
-{{{
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
-\end{eqnarray}
-}}}
-in the current format.
== Admonitions ==
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-{{{block}}}, {{{warning}}}, {{{notice}}}, {{{hint}}}, {{{question}}}, and
{{{summary}}}.
-The box is defined by begin and end tags such as {{{!bhint}}} and
{{{!ehint}}}.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading //Hint// (with number)
-appears, while outside exercises the {{{hint}}} environment gives a
-box with some admonition icon, text and/or colored background.)
+{{{block}}}, {{{warning}}}, {{{notice}}}, {{{question}}}, and
{{{summary}}}.
+The box is defined by begin and end tags such as {{{!bnotice}}} and
{{{!enotice}}}.
The title of the box is fully customizable.
Here are a few examples:
@@ -2712,9 +2709,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -2997,6 +2994,7 @@
== Emacs Doconce Formatter ==
+
The file
[[https://doconce.googlecode.com/hg/misc/.doconce-mode.el|.doconce-mode.el]]
in the Doconce source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3076,7 +3074,9 @@
<wiki:comment> doconce-adjusted styles: easy to switch between styles
since </wiki:comment>
<wiki:comment> font sizes are compatible </wiki:comment>
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
{{{
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3091,6 +3091,16 @@
== LaTeX Beamer Slides ==
+Not yet written...
+
+=== Themes ===
+
+Four themes come with Doconce: {{{X_Y}}}, where {{{X}}} is {{{blue}}} or
{{{red}}}
+(the main color of the slides) and {{{Y}}} is
[[http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf|
{{{plain}}}]]
+for simple layout and
+[[http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf|
{{{shadow}}}]]
+for shadowed boxes and more visual structure in the slides.
+
= Mako Programming =
The [[http://docs.makotemplates.org/|Mako]] templating engine is used
@@ -3100,6 +3110,14 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+//Warning.//
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like {{{${var}}}} to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., {{{${\cal O}(\Delta x^2)$}}} which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+
== The Basics of Mako ==
Just a preliminary sketch of some Mako code (next example is better!):
@@ -3275,6 +3293,15 @@
== General Problems ==
+=== Spellcheck reports a lot of mistakes related LaTeX math ===
+
+The {{{doconce spellcheck}}} command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant {{{tmp_missing_*}}} file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
=== Doconce aborts because of a syntax error that is not an error ===
Doconce searches for typical syntax errors and usually aborts the
@@ -3299,6 +3326,26 @@
* Strings with {{{'T<%.1f'}}} look as openings of Mako blocks ({{{<%}}});
change to {{{'T < %.1f'}}} to avoid this confusion.
+=== The Mako preprocessor claims a variable is undefined ===
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, {{{{\cal O}(\Delta x^2)}}} is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use {{{${}}} anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is {{{${}^+$}}} type of indication of superscripts.
+A suggested rewrite is {{{$\,{}^+$}}}.
+
+The error message will ask you to rerun {{{doconce}}} with
+{{{--mako_strict_undefined}}}, which will display the variable that
+is confusing Mako. However, do not continue to use
+{{{--mako_strict_undefined}}} while you are debugging because this
+variable will then always be undefined in that mode.
+Use {{{# #ifdef}}} directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without {{{--mako_strict_undefined}}}).
+
=== Something goes wrong in the preprocessing step ===
You can examine {{{tmp_preprocess__filename}}} and
{{{tmp_mako__filename}}},
@@ -3670,6 +3717,14 @@
further.
== Problems with HTML Output ==
+
+=== MathJax formulas are not properly rendered ===
+
+Here are some common problems:
+
+
+ * Two equations cannot have identical label (this error often arises
from copying and pasting equations)
+ * {{{[}}} and {{{]}}} brackets must sometimes be replaced by
{{{\lbrack}}} and {{{\rbrack}}}
=== How can I change the layout of the HTML page? ===
=======================================
--- /doc/demos/manual/manual.do.txt Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.do.txt Fri Jun 28 09:22:02 2013
@@ -755,7 +755,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with `===` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in `html` output such that search engines can make use of the them.
===== Bibliography =====
@@ -924,6 +928,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes `|` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+!bc
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+!ec
+
Note that not all formats offer alignment of heading or entries
in tables (`rst` and `sphinx` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -936,6 +953,33 @@
where `X` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the `doconce csv2table` utility:
+
+!bc sys
+Terminal> doconce csv2table somefile.csv > table.do.txt
+!ec
+This is a quick way of writing tables. For example, we can
+write a text file `tmp.csv` with
+
+!bc dat
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+!ec
+Running `doconce csv2table tmp.csv` creates the table
+
+!bc
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+!ec
+
===== Exercises, Problems, Projects, and Examples =====
Doconce has special support for four types of "exercises", named
@@ -1312,6 +1356,7 @@
\end{align}
|et
!ec
+# #ifdef EXTRA
Here is the result:
!bt
@@ -1320,6 +1365,7 @@
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. label{myeq2}
\end{align}
!et
+# #endif
The support of LaTeX mathematics varies among the formats:
@@ -1412,6 +1458,7 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
+# #ifdef EXTRA
__Example.__ Suppose we have the following commands in
`newcommand_replace.tex`:
@@ -1436,23 +1483,20 @@
\eeqa
!et
in the current format.
+# #endif
===== Admonitions =====
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-`block`, `warning`, `notice`, `hint`, `question`, and `summary`.
-The box is defined by begin and end tags such as `!bhint` and `!ehint`.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the `hint` environment gives a
-box with some admonition icon, text and/or colored background.)
+`block`, `warning`, `notice`, `question`, and `summary`.
+The box is defined by begin and end tags such as `!bnotice` and `!enotice`.
The title of the box is fully customizable.
Here are a few examples:
@@ -1462,9 +1506,9 @@
Here is a warning!
|ewarning
-|bhint
+|bnotice Hint
This is a hint.
-|ehint
+|enotice
|bblock This is a block.
A block has never any icon.
@@ -1488,9 +1532,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -1766,6 +1810,10 @@
===== Emacs Doconce Formatter =====
label{emacs:doconce}
+
+## Note: check http://www.latex-community.org/viewtopic.php?f=28&t=208
+## for highly configurable latex editors that perhaps can be adapted
+## to doconce (Kile seems to be the choice because of extensibility)
The
file ".doconce-mode.el": "https://doconce.googlecode.com/hg/misc/.doconce-mode.el"
in the Doconce source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -1854,7 +1902,9 @@
# doconce-adjusted styles: easy to switch between styles since
# font sizes are compatible
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
!bc sys
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -1871,6 +1921,17 @@
===== LaTeX Beamer Slides =====
+Not yet written...
+
+=== Themes ===
+
+Four themes come with Doconce: `X_Y`, where `X` is `blue` or `red`
+(the main color of the slides) and `Y` is "`plain`":
+"http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf"
+for simple layout and
+"`shadow`": "http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf"
+for shadowed boxes and more visual structure in the slides.
+
======= Mako Programming =======
The "Mako": "http://docs.makotemplates.org/" templating engine is used
@@ -1880,6 +1941,15 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+!bwarning
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like `${var}` to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., `${\cal O}(\Delta x^2)$` which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+!ewarning
+
===== The Basics of Mako =====
Just a preliminary sketch of some Mako code (next example is better!):
@@ -2055,6 +2125,15 @@
===== General Problems =====
+=== Spellcheck reports a lot of mistakes related LaTeX math ===
+
+The `doconce spellcheck` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant `tmp_missing_*` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
=== Doconce aborts because of a syntax error that is not an error ===
Doconce searches for typical syntax errors and usually aborts the
@@ -2079,6 +2158,26 @@
* Strings with `'T<%.1f'` look as openings of Mako blocks (`<%`); change
to `'T < %.1f'` to avoid this confusion.
+=== The Mako preprocessor claims a variable is undefined ===
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, ${\cal O}(\Delta x^2)$ is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use `${` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is `${}^+$` type of indication of superscripts.
+A suggested rewrite is `$\,{}^+$`.
+
+The error message will ask you to rerun `doconce` with
+`--mako_strict_undefined`, which will display the variable that
+is confusing Mako. However, do not continue to use
+`--mako_strict_undefined` while you are debugging because this
+variable will then always be undefined in that mode.
+Use `# #ifdef` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without `--mako_strict_undefined`).
+
=== Something goes wrong in the preprocessing step ===
You can examine `tmp_preprocess__filename` and `tmp_mako__filename`,
@@ -2464,6 +2563,14 @@
===== Problems with HTML Output =====
+=== MathJax formulas are not properly rendered ===
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+ * `[` and `]` brackets must sometimes be replaced by `\lbrack` and
`\rbrack`
+
=== How can I change the layout of the HTML page? ===
The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /doc/demos/manual/manual.epytext Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.epytext Fri Jun 28 09:22:02 2013
@@ -1,6 +1,6 @@
TITLE: Doconce Description
BY: Hans Petter Langtangen (Center for Biomedical Computing, Simula
Research Laboratory, and Department of Informatics, University of Oslo)
-DATE: May 29, 2013
+DATE: Jun 28, 2013
What Is Doconce?
================
@@ -548,7 +548,7 @@
=============================
Transformation of a Doconce document C{mydoc.do.txt} to various other
-formats applies the script C{doconce format}::
+formats apply the script C{doconce format}::
Terminal> doconce format format mydoc.do.txt
@@ -2120,7 +2120,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with C{===} heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in C{html} output such that search engines can make use of the them.
Bibliography
------------
@@ -2297,6 +2301,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes C{|} can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like::
+
+
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+
+
Note that not all formats offer alignment of heading or entries
in tables (C{rst} and C{sphinx} are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2309,6 +2326,33 @@
where C{X} is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the C{doconce csv2table} utility::
+
+
+ Terminal> doconce csv2table somefile.csv > table.do.txt
+
+This is a quick way of writing tables. For example, we can
+write a text file C{tmp.csv} with::
+
+
+ time, velocity, acceleration
+ 0.0, 1.4186, -5.01
+ 2.0, 1.376512, 11.919
+ 4.0, 1.1E+1, 14.717624
+
+Running C{doconce csv2table tmp.csv} creates the table::
+
+
+ |------c--------------c--------------c-------|
+ | time | velocity | acceleration |
+ |------c--------------c--------------c-------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------------------|
+
+
Exercises, Problems, Projects, and Examples
-------------------------------------------
@@ -2710,13 +2754,6 @@
it causes problems for Epytext.
-Here is the result::
-
-
- NOTE: A verbatim block has been removed because
- it causes problems for Epytext.
-
-
The support of LaTeX mathematics varies among the formats:
@@ -2809,59 +2846,20 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-I{Example.} Suppose we have the following commands in
-C{newcommand_replace.tex}::
-
-
-
- NOTE: A verbatim block has been removed because
- it causes problems for Epytext.
-
-
-
-and these in C{newcommands_keep.tex}::
-
-
-
- NOTE: A verbatim block has been removed because
- it causes problems for Epytext.
-
-
-
-The LaTeX block::
-
-
-
- NOTE: A verbatim block has been removed because
- it causes problems for Epytext.
-
-
-will then be rendered to::
-
-
- NOTE: A verbatim block has been removed because
- it causes problems for Epytext.
-
-
-in the current format.
Admonitions
-----------
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-C{block}, C{warning}, C{notice}, C{hint}, C{question}, and C{summary}.
-The box is defined by begin and end tags such as C{!bhint} and C{!ehint}.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading I{Hint} (with number)
-appears, while outside exercises the C{hint} environment gives a
-box with some admonition icon, text and/or colored background.)
+C{block}, C{warning}, C{notice}, C{question}, and C{summary}.
+The box is defined by begin and end tags such as C{!bnotice} and
C{!enotice}.
The title of the box is fully customizable.
Here are a few examples::
@@ -2871,9 +2869,9 @@
Here is a warning!
!ewarning
- !bhint
+ !bnotice Hint
This is a hint.
- !ehint
+ !enotice
!bblock This is a block.
A block has never any icon.
@@ -3257,7 +3255,9 @@
------------
-Text is missing... Just a very preliminary sketch of commands::
+Not yet written...
+
+Just a very preliminary sketch of commands::
Terminal> doconce format html myslides \
@@ -3277,6 +3277,17 @@
LaTeX Beamer Slides
-------------------
+Not yet written...
+
+Themes
+~~~~~~
+
+Four themes come with Doconce: C{X_Y}, where C{X} is C{blue} or C{red}
+(the main color of the slides) and C{Y} is
U{C{plain}<http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf>}
+for simple layout and
+U{C{shadow}<http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf>}
+for shadowed boxes and more visual structure in the slides.
+
Mako Programming
================
@@ -3287,6 +3298,14 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+I{Warning.}
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like C{${var}} to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., C{${\cal O}(\Delta x^2)$} which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+
The Basics of Mako
------------------
@@ -3450,6 +3469,16 @@
General Problems
----------------
+Spellcheck reports a lot of mistakes related LaTeX math
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The C{doconce spellcheck} command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant C{tmp_missing_*} file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
Doconce aborts because of a syntax error that is not an error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3477,6 +3506,27 @@
- Strings with C{'T<%.1f'} look as openings of Mako blocks (C{<%}); change
to C{'T < %.1f'} to avoid this confusion.
+The Mako preprocessor claims a variable is undefined
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, M{{\cal O}(\Delta x^2)} is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use C{${} anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is C{${}^+$} type of indication of superscripts.
+A suggested rewrite is C{$\,{}^+$}.
+
+The error message will ask you to rerun C{doconce} with
+C{--mako_strict_undefined}, which will display the variable that
+is confusing Mako. However, do not continue to use
+C{--mako_strict_undefined} while you are debugging because this
+variable will then always be undefined in that mode.
+Use C{# #ifdef} directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without C{--mako_strict_undefined}).
+
Something goes wrong in the preprocessing step
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3912,6 +3962,15 @@
Problems with HTML Output
-------------------------
+
+MathJax formulas are not properly rendered
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some common problems:
+
+ - Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+ - C{[} and C{]} brackets must sometimes be replaced by C{\lbrack} and
C{\rbrack}
How can I change the layout of the HTML page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================
--- /doc/demos/manual/manual.gwiki Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.gwiki Fri Jun 28 09:22:02 2013
@@ -1,7 +1,7 @@
#summary Doconce Description
By *Hans Petter Langtangen*
-==== May 29, 2013 ====
+==== Jun 28, 2013 ====
<wiki:comment> lines beginning with # are doconce comment lines
</wiki:comment>
<wiki:comment> (documents can also have mako comment lines) </wiki:comment>
@@ -518,7 +518,7 @@
Transformation of a Doconce document `mydoc.do.txt` to various other
-formats applies the script `doconce format`:
+formats apply the script `doconce format`:
{{{
Terminal> doconce format format mydoc.do.txt
}}}
@@ -2007,7 +2007,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with `===` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in `html` output such that search engines can make use of the them.
==== Bibliography ====
@@ -2173,6 +2177,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes `|` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+{{{
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+}}}
+
Note that not all formats offer alignment of heading or entries
in tables (`rst` and `sphinx` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2184,6 +2201,33 @@
makes Doconce dump each table to CSV format in a file `table_X.csv`,
where `X` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+
+Data in CSV format can be transformed to Doconce table format
+by the `doconce csv2table` utility:
+
+{{{
+Terminal> doconce csv2table somefile.csv > table.do.txt
+}}}
+This is a quick way of writing tables. For example, we can
+write a text file `tmp.csv` with
+
+{{{
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+}}}
+Running `doconce csv2table tmp.csv` creates the table
+
+{{{
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+}}}
==== Exercises, Problems, Projects, and Examples ====
@@ -2583,14 +2627,6 @@
\end{align}
!et
}}}
-Here is the result:
-
-{{{
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. label{myeq2}
-\end{align}
-}}}
The support of LaTeX mathematics varies among the formats:
@@ -2667,58 +2703,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-*Example.* Suppose we have the following commands in
-`newcommand_replace.tex`:
-
-{{{
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-}}}
-
-and these in `newcommands_keep.tex`:
-
-{{{
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-}}}
-
-The LaTeX block
-{{{
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-}}}
-will then be rendered to
-{{{
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
-\end{eqnarray}
-}}}
-in the current format.
==== Admonitions ====
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-`block`, `warning`, `notice`, `hint`, `question`, and `summary`.
-The box is defined by begin and end tags such as `!bhint` and `!ehint`.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the `hint` environment gives a
-box with some admonition icon, text and/or colored background.)
+`block`, `warning`, `notice`, `question`, and `summary`.
+The box is defined by begin and end tags such as `!bnotice` and `!enotice`.
The title of the box is fully customizable.
Here are a few examples:
@@ -2728,9 +2725,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3091,7 +3088,9 @@
<wiki:comment> doconce-adjusted styles: easy to switch between styles
since </wiki:comment>
<wiki:comment> font sizes are compatible </wiki:comment>
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
{{{
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3106,6 +3105,16 @@
==== LaTeX Beamer Slides ====
+Not yet written...
+
+==== Themes ====
+
+Four themes come with Doconce: `X_Y`, where `X` is `blue` or `red`
+(the main color of the slides) and `Y` is
[http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf `plain`]
+for simple layout and
+[http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf
`shadow`]
+for shadowed boxes and more visual structure in the slides.
+
== Mako Programming ==
The [http://docs.makotemplates.org/ Mako] templating engine is used
@@ -3115,6 +3124,14 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+*Warning.*
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like `${var}` to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., `${\cal O}(\Delta x^2)$` which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+
==== The Basics of Mako ====
Just a preliminary sketch of some Mako code (next example is better!):
@@ -3289,6 +3306,15 @@
==== General Problems ====
+==== Spellcheck reports a lot of mistakes related LaTeX math ====
+
+The `doconce spellcheck` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant `tmp_missing_*` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
==== Doconce aborts because of a syntax error that is not an error ====
Doconce searches for typical syntax errors and usually aborts the
@@ -3313,6 +3339,26 @@
* Strings with `'T<%.1f'` look as openings of Mako blocks (`<%`);
change to `'T < %.1f'` to avoid this confusion.
+==== The Mako preprocessor claims a variable is undefined ====
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, `{\cal O}(\Delta x^2)` is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use `${` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is `${}^+$` type of indication of superscripts.
+A suggested rewrite is `$\,{}^+$`.
+
+The error message will ask you to rerun `doconce` with
+`--mako_strict_undefined`, which will display the variable that
+is confusing Mako. However, do not continue to use
+`--mako_strict_undefined` while you are debugging because this
+variable will then always be undefined in that mode.
+Use `# #ifdef` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without `--mako_strict_undefined`).
+
==== Something goes wrong in the preprocessing step ====
You can examine `tmp_preprocess__filename` and `tmp_mako__filename`,
@@ -3685,6 +3731,14 @@
==== Problems with HTML Output ====
+==== MathJax formulas are not properly rendered ====
+
+Here are some common problems:
+
+
+ * Two equations cannot have identical label (this error often arises
from copying and pasting equations)
+ * `[` and `]` brackets must sometimes be replaced by `\lbrack` and
`\rbrack`
+
==== How can I change the layout of the HTML page? ====
The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /doc/demos/manual/manual.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.html Fri Jun 28 09:22:02 2013
@@ -42,7 +42,7 @@
-webkit-border-radius: 4px; -moz-border-radius: 4px;
border-radius: 4px
color: #555;
- background-color: whiteSmoke;
+ background-color: #f8f8f8;
background-position: 10px 5px;
background-repeat: no-repeat;
background-size: 38px;
@@ -56,7 +56,6 @@
.alert-notice { background-image:
url(https://doconce.googlecode.com/hg/bundled/html_images/small_gray_notice.png);
}
.alert-summary {
background-image:url(https://doconce.googlecode.com/hg/bundled/html_images/small_gray_summary.png);
}
.alert-warning { background-image:
url(https://doconce.googlecode.com/hg/bundled/html_images/small_gray_warning.png);
}
- .alert-hint { background-image:
url(https://doconce.googlecode.com/hg/bundled/html_images/small_gray_hint.png);
}
.alert-question
{background-image:url(https://doconce.googlecode.com/hg/bundled/html_images/small_gray_question.png);
}
</style>
@@ -179,148 +178,161 @@
(' HTML5 Slides ', 2, None, '___sec75'),
(' Potential Problems ', 3, None, '___sec76'),
(' LaTeX Beamer Slides ', 2, None, '___sec77'),
- (' Mako Programming ', 1, None, '___sec78'),
- (' The Basics of Mako ', 2, None, '___sec79'),
+ (' Themes ', 3, None, '___sec78'),
+ (' Mako Programming ', 1, None, '___sec79'),
+ (' The Basics of Mako ', 2, None, '___sec80'),
(' Example: Defining a Theorem Environment ',
2,
'manual:theorem:envir',
'manual:theorem:envir'),
- (' Troubleshooting ', 1, None, '___sec81'),
- (' Disclaimer ', 2, None, '___sec82'),
- (' General Problems ', 2, None, '___sec83'),
+ (' Troubleshooting ', 1, None, '___sec82'),
+ (' Disclaimer ', 2, None, '___sec83'),
+ (' General Problems ', 2, None, '___sec84'),
+ (' Spellcheck reports a lot of mistakes related LaTeX math ',
+ 3,
+ None,
+ '___sec85'),
(' Doconce aborts because of a syntax error that is not an
error ',
3,
None,
- '___sec84'),
+ '___sec86'),
(' The Mako preprocessor is seemingly not run ',
3,
None,
- '___sec85'),
+ '___sec87'),
(' The Mako preprocessor is fooled by Doconce text ',
3,
None,
- '___sec86'),
+ '___sec88'),
+ (' The Mako preprocessor claims a variable is undefined ',
+ 3,
+ None,
+ '___sec89'),
(' Something goes wrong in the preprocessing step ',
3,
None,
- '___sec87'),
- (' Figure captions are incomplete ', 3, None, '___sec88'),
- (' Preprocessor directives do not work ', 3,
None, '___sec89'),
- (' Problems with boldface and emphasize ', 3,
None, '___sec90'),
+ '___sec90'),
+ (' Figure captions are incomplete ', 3, None, '___sec91'),
+ (' Preprocessor directives do not work ', 3,
None, '___sec92'),
+ (' Problems with boldface and emphasize ', 3,
None, '___sec93'),
(' Links to local directories do not work ',
3,
None,
- '___sec91'),
- (' Links are not typeset correctly ', 3, None, '___sec92'),
- (' Inline verbatim code is not detected ', 3,
None, '___sec93'),
+ '___sec94'),
+ (' Links are not typeset correctly ', 3, None, '___sec95'),
+ (' Inline verbatim code is not detected ', 3,
None, '___sec96'),
(' Inline verbatim text is not formatted correctly ',
3,
None,
- '___sec94'),
- (' Strange non-English characters ', 3, None, '___sec95'),
- (' Wrong Norwegian charcters ', 3, None, '___sec96'),
+ '___sec97'),
+ (' Strange non-English characters ', 3, None, '___sec98'),
+ (' Wrong Norwegian charcters ', 3, None, '___sec99'),
(' Too short underlining of reST headlines ',
3,
None,
- '___sec97'),
+ '___sec100'),
(' Found !bt but no tex blocks extracted (BUG) ',
3,
None,
- '___sec98'),
+ '___sec101'),
(' Examples are typset with environment delimiters visible ',
3,
None,
- '___sec99'),
+ '___sec102'),
(' Emacs editing does not work properly because of "regexp
overflow" ',
3,
None,
- '___sec100'),
- (' Problems with code or Tex Blocks ', 2, None, '___sec101'),
- (' Code or math block errors in reST ', 3,
None, '___sec102'),
+ '___sec103'),
+ (' Problems with code or Tex Blocks ', 2, None, '___sec104'),
+ (' Code or math block errors in reST ', 3,
None, '___sec105'),
(' Strange errors around code or TeX blocks in reST ',
3,
None,
- '___sec103'),
+ '___sec106'),
(' Something is wrong with a verbatim code block ',
3,
None,
- '___sec104'),
+ '___sec107'),
(' Code/TeX block is not shown in reST format ',
3,
None,
- '___sec105'),
+ '___sec108'),
(' Verbatim code blocks inside lists look ugly ',
3,
None,
- '___sec106'),
+ '___sec109'),
(' LaTeX code blocks inside lists look ugly ',
3,
None,
- '___sec107'),
- (' Problems with reST/Sphinx Output ', 2, None, '___sec108'),
- (' Title level inconsistent ', 3, None, '___sec109'),
- (' Lists do not appear in .rst files ', 3,
None, '___sec110'),
+ '___sec110'),
+ (' Problems with reST/Sphinx Output ', 2, None, '___sec111'),
+ (' Title level inconsistent ', 3, None, '___sec112'),
+ (' Lists do not appear in .rst files ', 3,
None, '___sec113'),
(' Error message "Undefined substitution..." from reST ',
3,
None,
- '___sec111'),
- (' Warning about duplicate link names ', 3,
None, '___sec112'),
- (' Inconsistent headings in reST ', 3, None, '___sec113'),
+ '___sec114'),
+ (' Warning about duplicate link names ', 3,
None, '___sec115'),
+ (' Inconsistent headings in reST ', 3, None, '___sec116'),
(' No code environment appears before "bc ipy" blocks ',
3,
None,
- '___sec114'),
- (' Problems with LaTeX Output ', 2, None, '___sec115'),
+ '___sec117'),
+ (' Problems with LaTeX Output ', 2, None, '___sec118'),
(' LaTeX does not like underscores in URLs ',
3,
None,
- '___sec116'),
+ '___sec119'),
(" Error when running latex: You must have 'pygmentize'
installed ",
3,
None,
- '___sec117'),
+ '___sec120'),
(' Why are the LaTeX section headings smaller than normal? ',
3,
None,
- '___sec118'),
+ '___sec121'),
(' Can I have LaTeX figures with shadows? ',
3,
None,
- '___sec119'),
+ '___sec122'),
(' How can I use my fancy LaTeX environments? ',
3,
None,
- '___sec120'),
- (' The LaTeX file does not compile ', 3, None, '___sec121'),
- (' Inline verbatim gives error ', 3, None, '___sec122'),
- (' Errors in figure captions ', 3, None, '___sec123'),
- (' Chapters are ignored ', 3, None, '___sec124'),
+ '___sec123'),
+ (' The LaTeX file does not compile ', 3, None, '___sec124'),
+ (' Inline verbatim gives error ', 3, None, '___sec125'),
+ (' Errors in figure captions ', 3, None, '___sec126'),
+ (' Chapters are ignored ', 3, None, '___sec127'),
(' I want to tune the top of the LaTeX file ',
3,
None,
- '___sec125'),
- (' Problems with gwiki Output ', 2, None, '___sec126'),
- (' Strange nested lists in gwiki ', 3, None, '___sec127'),
+ '___sec128'),
+ (' Problems with gwiki Output ', 2, None, '___sec129'),
+ (' Strange nested lists in gwiki ', 3, None, '___sec130'),
(' Lists in gwiki look ugly in the gwiki source ',
3,
+ None,
+ '___sec131'),
+ (' Problems with HTML Output ', 2, None, '___sec132'),
+ (' MathJax formulas are not properly rendered ',
+ 3,
None,
- '___sec128'),
- (' Problems with HTML Output ', 2, None, '___sec129'),
+ '___sec133'),
(' How can I change the layout of the HTML page? ',
3,
None,
- '___sec130'),
+ '___sec134'),
(' Why do figures look ugly when using HTML templates? ',
3,
None,
- '___sec131'),
- (' Debugging ', 2, None, '___sec132'),
- (' Basic Parsing Ideas ', 1, None, '___sec133'),
+ '___sec135'),
+ (' Debugging ', 2, None, '___sec136'),
+ (' Basic Parsing Ideas ', 1, None, '___sec137'),
(' Typesetting of Function Arguments, Return Values, and
Variables ',
2,
None,
- '___sec134'),
- (' References ', 1, None, '___sec135')]}
+ '___sec138'),
+ (' References ', 1, None, '___sec139')]}
end of tocinfo -->
<body>
@@ -342,23 +354,10 @@
<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7">
-<!-- newcommands_keep.tex -->
-$$
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-$$
+
-<!-- newcommands_replace.tex -->
-$$
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-$$
+
@@ -385,7 +384,7 @@
<center>[1] <b>Center for Biomedical Computing, Simula Research
Laboratory</b></center>
<center>[2] <b>Department of Informatics, University of Oslo</b></center>
<p>
-<center><h4>May 29, 2013</h4></center> <!-- date -->
+<center><h4>Jun 28, 2013</h4></center> <!-- date -->
<p>
<!-- lines beginning with # are doconce comment lines -->
<!-- (documents can also have mako comment lines) -->
@@ -1014,7 +1013,7 @@
<p>
Transformation of a Doconce document <code>mydoc.do.txt</code> to various
other
-formats applies the script <code>doconce format</code>:
+formats apply the script <code>doconce format</code>:
<!-- begin verbatim block sys-->
<pre><code>Terminal> doconce format format mydoc.do.txt
</code></pre>
@@ -2776,7 +2775,12 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with <code>===</code> heading,
+the index keywords should be placed above the heading.
+
+<p>
+The keywords in the index are automatically placed in a meta
+tag in <code>html</code> output such that search engines can make use of
the them.
<h3>Bibliography <a name="___sec53"></a></h3>
@@ -2969,6 +2973,22 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes <code>|</code> can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+<p>
+<!-- begin verbatim block -->
+<pre><code> |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+</code></pre>
+<!-- end verbatim block -->
+
+<p>
Note that not all formats offer alignment of heading or entries
in tables (<code>rst</code> and <code>sphinx</code> are examples). Also
note that
Doconce tables are very simple: neither entries nor
@@ -2982,6 +3002,40 @@
where <code>X</code> is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+<p>
+Data in CSV format can be transformed to Doconce table format
+by the <code>doconce csv2table</code> utility:
+
+<p>
+<!-- begin verbatim block sys-->
+<pre><code>Terminal> doconce csv2table somefile.csv > table.do.txt
+</code></pre>
+<!-- end verbatim block -->
+This is a quick way of writing tables. For example, we can
+write a text file <code>tmp.csv</code> with
+
+<p>
+<!-- begin verbatim block dat-->
+<pre><code>time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+</code></pre>
+<!-- end verbatim block -->
+Running <code>doconce csv2table tmp.csv</code> creates the table
+
+<p>
+<!-- begin verbatim block -->
+<pre><code>|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+</code></pre>
+<!-- end verbatim block -->
+
<h3>Exercises, Problems, Projects, and Examples <a
name="___sec62"></a></h3>
<p>
@@ -3418,16 +3472,6 @@
!et
</code></pre>
<!-- end verbatim block -->
-Here is the result:
-
-<p>
-$$
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, \label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. \label{myeq2}
-\end{align}
-$$
-
<p>
The support of LaTeX mathematics varies among the formats:
@@ -3532,57 +3576,11 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-<p>
-<b>Example.</b>
-Suppose we have the following commands in
-<code>newcommand_replace.tex</code>:
-
-<p>
-<!-- begin verbatim block latexpro-->
-<pre><code>\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-</code></pre>
-<!-- end verbatim block -->
-
-<p>
-and these in <code>newcommands_keep.tex</code>:
-
-<p>
-<!-- begin verbatim block latexpro-->
-<pre><code>\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-</code></pre>
-<!-- end verbatim block -->
-
-<p>
-The LaTeX block
-<!-- begin verbatim block -->
-<pre><code>\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-</code></pre>
-<!-- end verbatim block -->
-will then be rendered to
-$$
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, \label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } \label{my:eq2}
-\end{eqnarray}
-$$
-
-in the current format.
-
<h3>Admonitions <a name="___sec67"></a></h3>
<p>
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
@@ -3590,12 +3588,8 @@
<p>
The following admonition environments are available:
-<code>block</code>, <code>warning</code>, <code>notice</code>,
<code>hint</code>, <code>question</code>, and <code>summary</code>.
-The box is defined by begin and end tags such as <code>!bhint</code> and
<code>!ehint</code>.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading <em>Hint</em> (with number)
-appears, while outside exercises the <code>hint</code> environment gives a
-box with some admonition icon, text and/or colored background.)
+<code>block</code>, <code>warning</code>, <code>notice</code>,
<code>question</code>, and <code>summary</code>.
+The box is defined by begin and end tags such as <code>!bnotice</code> and
<code>!enotice</code>.
The title of the box is fully customizable.
<p>
@@ -3607,9 +3601,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3635,7 +3629,7 @@
Here is a warning!
</div>
<p>
-<div class="alert alert-block alert-hint alert-text-normal"><b>Hint.</b>
+<div class="alert alert-block alert-notice alert-text-normal"><b>Hint.</b>
This is a hint.
</div>
<p>
@@ -4041,8 +4035,11 @@
<!-- doconce-adjusted styles: easy to switch between styles since -->
<!-- font sizes are compatible -->
+<p>
+Not yet written...
+
<p>
-Text is missing... Just a very preliminary sketch of commands:
+Just a very preliminary sketch of commands:
<!-- begin verbatim block sys-->
<pre><code>Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -4064,7 +4061,19 @@
<h3>LaTeX Beamer Slides <a name="___sec77"></a></h3>
-<h2>Mako Programming <a name="___sec78"></a></h2>
+<p>
+Not yet written...
+
+<h4>Themes <a name="___sec78"></a></h4>
+
+<p>
+Four themes come with Doconce: <code>X_Y</code>, where <code>X</code> is
<code>blue</code> or <code>red</code>
+(the main color of the slides) and <code>Y</code> is <a
href="http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf"><tt>plain</tt></a>
+for simple layout and
+<a
href="http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf"><tt>shadow</tt></a>
+for shadowed boxes and more visual structure in the slides.
+
+<h2>Mako Programming <a name="___sec79"></a></h2>
<p>
The <a href="http://docs.makotemplates.org/">Mako</a> templating engine is
used
@@ -4074,7 +4083,16 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
-<h3>The Basics of Mako <a name="___sec79"></a></h3>
+<p>
+<div class="alert alert-block alert-warning
alert-text-normal"><b>Warning.</b>
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like <code>${var}</code> to
extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., <code>${\cal O}(\Delta x^2)$</code> which looks
like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+</div>
+<h3>The Basics of Mako <a name="___sec80"></a></h3>
<p>
Just a preliminary sketch of some Mako code (next example is better!):
@@ -4243,9 +4261,9 @@
the <code>ptex2tex</code> program with all its flexibility for choosing
environments.
Also <code>doconce ptex2tex</code> has some flexibility for typesetting
computer code.
-<h2>Troubleshooting <a name="___sec81"></a></h2>
+<h2>Troubleshooting <a name="___sec82"></a></h2>
-<h3>Disclaimer <a name="___sec82"></a></h3>
+<h3>Disclaimer <a name="___sec83"></a></h3>
<p>
Doconce has some support for syntax checking. If you encounter Python
@@ -4256,9 +4274,19 @@
regular expressions may sometimes fail. Therefore, there is a chance that
legal
Doconce syntax is not treated properly.
-<h3>General Problems <a name="___sec83"></a></h3>
+<h3>General Problems <a name="___sec84"></a></h3>
-<h4>Doconce aborts because of a syntax error that is not an error <a
name="___sec84"></a></h4>
+<h4>Spellcheck reports a lot of mistakes related LaTeX math <a
name="___sec85"></a></h4>
+
+<p>
+The <code>doconce spellcheck</code> command should ignore LaTeX math, but
if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant <code>tmp_missing_*</code> file and search for the math
expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
+<h4>Doconce aborts because of a syntax error that is not an error <a
name="___sec86"></a></h4>
<p>
Doconce searches for typical syntax errors and usually aborts the
@@ -4268,7 +4296,7 @@
<code>--no_abort</code> option on the command line. You may send an email
to the Doconce author at <code>h...@simula.no</code> and report the problem.
-<h4>The Mako preprocessor is seemingly not run <a
name="___sec85"></a></h4>
+<h4>The Mako preprocessor is seemingly not run <a
name="___sec87"></a></h4>
<p>
If you have lines starting with <code>%</code> inside code segments (for
example,
@@ -4277,7 +4305,7 @@
this problem and avoids running Mako. Examine the output from
Doconce: warnings are issued if Mako is not run.
-<h4>The Mako preprocessor is fooled by Doconce text <a
name="___sec86"></a></h4>
+<h4>The Mako preprocessor is fooled by Doconce text <a
name="___sec88"></a></h4>
<p>
Here are possible problems for Mako:
@@ -4289,7 +4317,29 @@
to <code>'T < %.1f'</code> to avoid this confusion.</li>
</ul>
-<h4>Something goes wrong in the preprocessing step <a
name="___sec87"></a></h4>
+<h4>The Mako preprocessor claims a variable is undefined <a
name="___sec89"></a></h4>
+
+<p>
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, \( {\cal O}(\Delta x^2) \) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use <code>${</code> anywhere in LaTeX
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is <code>${}^+$</code> type of indication of
superscripts.
+A suggested rewrite is <code>$\,{}^+$</code>.
+
+<p>
+The error message will ask you to rerun <code>doconce</code> with
+<code>--mako_strict_undefined</code>, which will display the variable that
+is confusing Mako. However, do not continue to use
+<code>--mako_strict_undefined</code> while you are debugging because this
+variable will then always be undefined in that mode.
+Use <code># #ifdef</code> directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without <code>--mako_strict_undefined</code>).
+
+<h4>Something goes wrong in the preprocessing step <a
name="___sec90"></a></h4>
<p>
You can examine <code>tmp_preprocess__filename</code> and
<code>tmp_mako__filename</code>,
@@ -4300,7 +4350,7 @@
of the output from Doconce to see exactly which preprocessors are run
and on which files.
-<h4>Figure captions are incomplete <a name="___sec88"></a></h4>
+<h4>Figure captions are incomplete <a name="___sec91"></a></h4>
<p>
If only the first part of a figure caption in the Doconce file is seen
@@ -4308,20 +4358,20 @@
occupies multiple lines in the Doconce file. The figure caption must
be written as <em>one line</em>, at the same line as the FIGURE keyword.
-<h4>Preprocessor directives do not work <a name="___sec89"></a></h4>
+<h4>Preprocessor directives do not work <a name="___sec92"></a></h4>
<p>
Make sure the preprocessor instructions, in Preprocess or Mako, have
correct syntax. Also make sure that you do not mix Preprocess and Mako
instructions. Doconce will then only run Preprocess.
-<h4>Problems with boldface and emphasize <a name="___sec90"></a></h4>
+<h4>Problems with boldface and emphasize <a name="___sec93"></a></h4>
<p>
Two boldface or emphasize expressions after each other are not rendered
correctly. Merge them into one common expression.
-<h4>Links to local directories do not work <a name="___sec91"></a></h4>
+<h4>Links to local directories do not work <a name="___sec94"></a></h4>
<p>
Links of the type
@@ -4340,7 +4390,7 @@
With plain <code>html</code> output only, you can link to whatever, but
remember
to move all files you link to if you move the primary <code>.html</code>
file.
-<h4>Links are not typeset correctly <a name="___sec92"></a></h4>
+<h4>Links are not typeset correctly <a name="___sec95"></a></h4>
<p>
Not all formats will allow formatting of the links. Verbatim words
@@ -4357,17 +4407,17 @@
The back-ticks must be removed, or the text can be reformulated as
in the line above it.
-<h4>Inline verbatim code is not detected <a name="___sec93"></a></h4>
+<h4>Inline verbatim code is not detected <a name="___sec96"></a></h4>
<p>
Make sure there is a space before the first back-tick.
-<h4>Inline verbatim text is not formatted correctly <a
name="___sec94"></a></h4>
+<h4>Inline verbatim text is not formatted correctly <a
name="___sec97"></a></h4>
<p>
Make sure there is whitespace surrounding the text in back-ticks.
-<h4>Strange non-English characters <a name="___sec95"></a></h4>
+<h4>Strange non-English characters <a name="___sec98"></a></h4>
<p>
The former reason for this problem is that Doconce could only work with
latin1
@@ -4389,7 +4439,7 @@
</code></pre>
<!-- end verbatim block -->
-<h4>Wrong Norwegian charcters <a name="___sec96"></a></h4>
+<h4>Wrong Norwegian charcters <a name="___sec99"></a></h4>
<p>
When Doconce documents have characters not in the standard ASCII set,
@@ -4397,20 +4447,20 @@
the section "Strange non-English characters" above for how to
run <code>doconce change_encoding</code> to change the encoding of the
Doconce file.
-<h4>Too short underlining of reST headlines <a name="___sec97"></a></h4>
+<h4>Too short underlining of reST headlines <a name="___sec100"></a></h4>
<p>
This may happen if there is a paragraph heading without
proceeding text before some section heading.
-<h4>Found !bt but no tex blocks extracted (BUG) <a
name="___sec98"></a></h4>
+<h4>Found !bt but no tex blocks extracted (BUG) <a
name="___sec101"></a></h4>
<p>
This message points to a bug, but has been resolved by removing blank lines
between the text and the first <code>!bt</code> (inserting the blanks
again did not
trigger the error message again...).
-<h4>Examples are typset with environment delimiters visible <a
name="___sec99"></a></h4>
+<h4>Examples are typset with environment delimiters visible <a
name="___sec102"></a></h4>
<p>
If you see an Example section containing <code>!bsubex</code>,
<code>!bsol</code>, or other
@@ -4419,7 +4469,7 @@
option <code>--examples_as_exercises</code>. The text in the example is
typeset
as is unless this option is included.
-<h4>Emacs editing does not work properly because of "regexp overflow" <a
name="___sec100"></a></h4>
+<h4>Emacs editing does not work properly because of "regexp overflow" <a
name="___sec103"></a></h4>
<p>
Sometimes the Doonce editing mode (see the section <a
href="#emacs:doconce">Emacs Doconce Formatter</a>) in Emacs
@@ -4430,9 +4480,9 @@
The error message comes with the Doconce file contains too much text
for Emacs to handle.
-<h3>Problems with code or Tex Blocks <a name="___sec101"></a></h3>
+<h3>Problems with code or Tex Blocks <a name="___sec104"></a></h3>
-<h4>Code or math block errors in reST <a name="___sec102"></a></h4>
+<h4>Code or math block errors in reST <a name="___sec105"></a></h4>
<p>
First note that a code or math block must come after some plain
@@ -4454,7 +4504,7 @@
at the preceding line will appear (which is the right way in reST to
indicate a verbatim block of text).
-<h4>Strange errors around code or TeX blocks in reST <a
name="___sec103"></a></h4>
+<h4>Strange errors around code or TeX blocks in reST <a
name="___sec106"></a></h4>
<p>
If <code>idx</code> commands for defining indices are placed inside
paragraphs,
@@ -4464,21 +4514,21 @@
other formats. The remedy is to define items for the index outside
paragraphs.
-<h4>Something is wrong with a verbatim code block <a
name="___sec104"></a></h4>
+<h4>Something is wrong with a verbatim code block <a
name="___sec107"></a></h4>
<p>
Check first that there is a "normal" sentence right before
the block (this is important for reST and similar
"ASCII-close" formats).
-<h4>Code/TeX block is not shown in reST format <a
name="___sec105"></a></h4>
+<h4>Code/TeX block is not shown in reST format <a
name="___sec108"></a></h4>
<p>
A comment right before a code or tex block will treat the whole
block also as a comment. It is important that there is normal
running text right before <code>!bt</code> and <code>!bc</code>
environments.
-<h4>Verbatim code blocks inside lists look ugly <a
name="___sec106"></a></h4>
+<h4>Verbatim code blocks inside lists look ugly <a
name="___sec109"></a></h4>
<p>
Read the the section <a href="#sec:verbatim:blocks">Blocks of Verbatim
Computer Code</a> above. Start the
@@ -4488,7 +4538,7 @@
paragraph headings instead. In fact, that is what is recommended:
avoid verbatim code blocks inside lists (it makes life easier).
-<h4>LaTeX code blocks inside lists look ugly <a name="___sec107"></a></h4>
+<h4>LaTeX code blocks inside lists look ugly <a name="___sec110"></a></h4>
<p>
Same solution as for computer code blocks as described in the
@@ -4496,36 +4546,36 @@
and that the rest of the non-LaTeX surrounding text is correctly indented.
Using paragraphs instead of list items is a good idea also here.
-<h3>Problems with reST/Sphinx Output <a name="___sec108"></a></h3>
+<h3>Problems with reST/Sphinx Output <a name="___sec111"></a></h3>
-<h4>Title level inconsistent <a name="___sec109"></a></h4>
+<h4>Title level inconsistent <a name="___sec112"></a></h4>
<p>
reST does not like jumps in the levels of headings. For example, you cannot
have a <code>===</code> (paragraph) heading after a <code>=======</code>
(section) heading without
a <code>=====</code> (subsection) heading in between.
-<h4>Lists do not appear in .rst files <a name="___sec110"></a></h4>
+<h4>Lists do not appear in .rst files <a name="___sec113"></a></h4>
<p>
Check if you have a comment right above the list. That comment
will include the list if the list is indentend. Remove the comment.
-<h4>Error message "Undefined substitution..." from reST <a
name="___sec111"></a></h4>
+<h4>Error message "Undefined substitution..." from reST <a
name="___sec114"></a></h4>
<p>
This may happen if there is much inline math in the text. reST cannot
understand inline LaTeX commands and interprets them as illegal code.
Just ignore these error messages.
-<h4>Warning about duplicate link names <a name="___sec112"></a></h4>
+<h4>Warning about duplicate link names <a name="___sec115"></a></h4>
<p>
Link names should be unique, but if (e.g.) "file" is used as link text
several places in a reST file, the links still work. The warning can
therefore be ignorned.
-<h4>Inconsistent headings in reST <a name="___sec113"></a></h4>
+<h4>Inconsistent headings in reST <a name="___sec116"></a></h4>
<p>
The <code>rst2*.py</code> and Sphinx converters abort if the headers of
sections
@@ -4535,7 +4585,7 @@
count the number of equality signs (or underscores if you use that)
and make sure they decrease by two every time a lower level is encountered.
-<h4>No code environment appears before "bc ipy" blocks <a
name="___sec114"></a></h4>
+<h4>No code environment appears before "bc ipy" blocks <a
name="___sec117"></a></h4>
<p>
The <code>!bc ipy</code> directive behaves this way for
<code>sphinx</code> output because
@@ -4543,9 +4593,9 @@
appropriate, shift to <code>!bc cod</code> or another specification of the
verbatim environment.
-<h3>Problems with LaTeX Output <a name="___sec115"></a></h3>
+<h3>Problems with LaTeX Output <a name="___sec118"></a></h3>
-<h4>LaTeX does not like underscores in URLs <a name="___sec116"></a></h4>
+<h4>LaTeX does not like underscores in URLs <a name="___sec119"></a></h4>
<p>
Suppose you have a URL reference like
@@ -4568,7 +4618,7 @@
<!-- end verbatim block -->
Verbatim text in links works fine with underscores.
-<h4>Error when running latex: You must have 'pygmentize' installed <a
name="___sec117"></a></h4>
+<h4>Error when running latex: You must have 'pygmentize' installed <a
name="___sec120"></a></h4>
<p>
This message points to the use of the minted style for typesetting verbatim
@@ -4585,7 +4635,7 @@
When this package is included, <code>latex</code> or <code>pdflatex</code>
runs the
<code>pygmentize</code> program and the <code>shell-escape</code> option
is required.
-<h4>Why are the LaTeX section headings smaller than normal? <a
name="___sec118"></a></h4>
+<h4>Why are the LaTeX section headings smaller than normal? <a
name="___sec121"></a></h4>
<p>
Doconce inserts a special command to make the headings
@@ -4611,7 +4661,7 @@
by replacing <code>[compact]</code> by <code>[compact,small]</code> as
parameter specification
for <code>titlesec</code>.
-<h4>Can I have LaTeX figures with shadows? <a name="___sec119"></a></h4>
+<h4>Can I have LaTeX figures with shadows? <a name="___sec122"></a></h4>
<p>
This is easy by including the <code>fancybox</code> and
<code>graphicx</code> packages
@@ -4627,14 +4677,14 @@
</code></pre>
<!-- end verbatim block -->
-<h4>How can I use my fancy LaTeX environments? <a
name="___sec120"></a></h4>
+<h4>How can I use my fancy LaTeX environments? <a
name="___sec123"></a></h4>
<p>
See the section <a href="#manual:theorem:envir">Example: Defining a
Theorem Environment</a> for how to make a custom
theorem environment also in Doconce, without using implementations
restricted to LaTeX.
-<h4>The LaTeX file does not compile <a name="___sec121"></a></h4>
+<h4>The LaTeX file does not compile <a name="___sec124"></a></h4>
<p>
If the problem is undefined control sequence involving
@@ -4646,7 +4696,7 @@
Doconce file) spans more than one line. Make sure, in the Doconce source,
that all inline verbatim text appears on the same line.
-<h4>Inline verbatim gives error <a name="___sec122"></a></h4>
+<h4>Inline verbatim gives error <a name="___sec125"></a></h4>
<p>
Check if the inline verbatim contains typical LaTeX commands, e.g.,
@@ -4666,7 +4716,7 @@
<!-- Could have doconce configure file where inline verbatim is -->
<!-- configured to be \fontsize... directly, not via ptex2tex \code{}. -->
-<h4>Errors in figure captions <a name="___sec123"></a></h4>
+<h4>Errors in figure captions <a name="___sec126"></a></h4>
<p>
Such errors typically arise from unbalanced curly braces, or dollar signs
@@ -4678,14 +4728,14 @@
a proper <code>texttt</code> command (since verbatim font constructions
does not work
inside figure captions) and precede underscores by backslash.)
-<h4>Chapters are ignored <a name="___sec124"></a></h4>
+<h4>Chapters are ignored <a name="___sec127"></a></h4>
<p>
The default LaTeX style is "article". If you chapters in the Doconce file,
you need to run <code>ptex2tex</code> with the option <code>-DBOOK</code>
to set the LaTeX
documentstyle to "book".
-<h4>I want to tune the top of the LaTeX file <a name="___sec125"></a></h4>
+<h4>I want to tune the top of the LaTeX file <a name="___sec128"></a></h4>
<p>
The top of the LaTeX file, as generated by Doconce, is very simple.
@@ -4713,15 +4763,15 @@
replaced by the hand-written LaTeX "top" file.</li>
</ol>
-<h3>Problems with gwiki Output <a name="___sec126"></a></h3>
+<h3>Problems with gwiki Output <a name="___sec129"></a></h3>
-<h4>Strange nested lists in gwiki <a name="___sec127"></a></h4>
+<h4>Strange nested lists in gwiki <a name="___sec130"></a></h4>
<p>
Doconce cannot handle nested lists correctly in the gwiki format.
Use nonnested lists or edit the <code>.gwiki</code> file directly.
-<h4>Lists in gwiki look ugly in the gwiki source <a
name="___sec128"></a></h4>
+<h4>Lists in gwiki look ugly in the gwiki source <a
name="___sec131"></a></h4>
<p>
Because the Google Code wiki format requires all text of a list item to
@@ -4731,9 +4781,22 @@
is seldom to be looked at - it is the Doconce source that one edits
further.
-<h3>Problems with HTML Output <a name="___sec129"></a></h3>
+<h3>Problems with HTML Output <a name="___sec132"></a></h3>
+
+<h4>MathJax formulas are not properly rendered <a
name="___sec133"></a></h4>
+
+<p>
+Here are some common problems:
+
+<p>
+
+<ul>
+ <li> Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)</li>
+ <li> <code>[</code> and <code>]</code> brackets must sometimes be
replaced by <code>\lbrack</code> and <code>\rbrack</code></li>
+</ul>
-<h4>How can I change the layout of the HTML page? <a
name="___sec130"></a></h4>
+<h4>How can I change the layout of the HTML page? <a
name="___sec134"></a></h4>
<p>
The easiest way is to edit the HTML style or the HTML code directly.
@@ -4775,7 +4838,7 @@
The easiest way is to get fancy layouts in HTML is to
use the <code>sphinx</code> format and one its many themes.
-<h4>Why do figures look ugly when using HTML templates? <a
name="___sec131"></a></h4>
+<h4>Why do figures look ugly when using HTML templates? <a
name="___sec135"></a></h4>
<p>
The HTML header that Doconce generates contain special styles for
@@ -4794,7 +4857,7 @@
</code></pre>
<!-- end verbatim block -->
-<h3>Debugging <a name="___sec132"></a></h3>
+<h3>Debugging <a name="___sec136"></a></h3>
<p>
Given a problem, extract a small portion of text surrounding the
@@ -4807,7 +4870,7 @@
Ideas" explains how the Doconce text is transformed into a specific
format, and you need to know these steps to make use of the logfile.
-<h2>Basic Parsing Ideas <a name="___sec133"></a></h2>
+<h2>Basic Parsing Ideas <a name="___sec137"></a></h2>
<p>
<!-- avoid list here since we have code in between (never a good idea) -->
@@ -4860,7 +4923,7 @@
the document to another, more complex format, say reST or
LaTeX, and work further on the document in this format.
-<h3>Typesetting of Function Arguments, Return Values, and Variables <a
name="___sec134"></a></h3>
+<h3>Typesetting of Function Arguments, Return Values, and Variables <a
name="___sec138"></a></h3>
<p>
As part of comments (or doc strings) in computer code one often wishes
@@ -4903,7 +4966,7 @@
the iterations.
</dl>
-<h2>References <a name="___sec135"></a></h2>
+<h2>References <a name="___sec139"></a></h2>
<h2>Bibliography</h2>
=======================================
--- /doc/demos/manual/manual.md Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.md Fri Jun 28 09:22:02 2013
@@ -1,6 +1,6 @@
% Doconce Description
% Hans Petter Langtangen at Center for Biomedical Computing, Simula
Research Laboratory and Department of Informatics, University of Oslo
-% May 29, 2013
+% Jun 28, 2013
<!-- lines beginning with # are doconce comment lines -->
<!-- (documents can also have mako comment lines) -->
@@ -596,7 +596,7 @@
## From Doconce to Other Formats
Transformation of a Doconce document `mydoc.do.txt` to various other
-formats applies the script `doconce format`:
+formats apply the script `doconce format`:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.Bash}
Terminal> doconce format format mydoc.do.txt
@@ -2265,7 +2265,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with `===` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in `html` output such that search engines can make use of the them.
### Bibliography
@@ -2445,6 +2449,20 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes `|` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
Note that not all formats offer alignment of heading or entries
in tables (`rst` and `sphinx` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2457,6 +2475,38 @@
where `X` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the `doconce csv2table` utility:
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.Bash}
+Terminal> doconce csv2table somefile.csv > table.do.txt
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a quick way of writing tables. For example, we can
+write a text file `tmp.csv` with
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.Python}
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Running `doconce csv2table tmp.csv` creates the table
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
### Exercises, Problems, Projects, and Examples
Doconce has special support for four types of "exercises", named
@@ -2881,20 +2931,6 @@
!et
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Here is the result:
-
-$$
-\begin{equation}
-{\partial u\over\partial t} = \nabla^2 u + f, \label{myeq1}
-\end{equation}
-$$
-
-$$
-\begin{equation}
-{\partial v\over\partial t} = \nabla\cdot(q(u)\nabla v) + g. \label{myeq2}
-\end{equation}
-$$
-
The support of LaTeX mathematics varies among the formats:
* Output in LaTeX (`latex` and `pdflatex` formats) has of course full
@@ -2992,62 +3028,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-*Example.* Suppose we have the following commands in
-`newcommand_replace.tex`:
-
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-and these in `newcommands_keep.tex`:
-
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The LaTeX block
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-\beqa
-\x\cdot\normalvec &=& 0, \label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep \label{my:eq2}
-\eeqa
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-will then be rendered to
-$$
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, \label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } \label{my:eq2}
-\end{eqnarray}
-$$
-in the current format.
### Admonitions
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-`block`, `warning`, `notice`, `hint`, `question`, and `summary`.
-The box is defined by begin and end tags such as `!bhint` and `!ehint`.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the `hint` environment gives a
-box with some admonition icon, text and/or colored background.)
+`block`, `warning`, `notice`, `question`, and `summary`.
+The box is defined by begin and end tags such as `!bnotice` and `!enotice`.
The title of the box is fully customizable.
Here are a few examples:
@@ -3058,9 +3051,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3464,7 +3457,9 @@
<!-- doconce-adjusted styles: easy to switch between styles since -->
<!-- font sizes are compatible -->
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.Bash}
Terminal> doconce format html myslides \
@@ -3483,6 +3478,16 @@
### LaTeX Beamer Slides
+Not yet written...
+
+#### Themes
+
+Four themes come with Doconce: `X_Y`, where `X` is `blue` or `red`
+(the main color of the slides) and `Y` is
[`plain`](http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf)
+for simple layout and
+[`shadow`](http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf)
+for shadowed boxes and more visual structure in the slides.
+
## Mako Programming
The [Mako](http://docs.makotemplates.org/) templating engine is used
@@ -3492,6 +3497,14 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+*Warning.*
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like `${var}` to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., `${\cal O}(\Delta x^2)$` which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+
### The Basics of Mako
Just a preliminary sketch of some Mako code (next example is better!):
@@ -3675,6 +3688,15 @@
### General Problems
+#### Spellcheck reports a lot of mistakes related LaTeX math
+
+The `doconce spellcheck` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant `tmp_missing_*` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
#### Doconce aborts because of a syntax error that is not an error
Doconce searches for typical syntax errors and usually aborts the
@@ -3699,6 +3721,26 @@
* Strings with `'T<%.1f'` look as openings of Mako blocks (`<%`); change
to `'T < %.1f'` to avoid this confusion.
+#### The Mako preprocessor claims a variable is undefined
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, ${\cal O}(\Delta x^2)$ is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use `${` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is `${}^+$` type of indication of superscripts.
+A suggested rewrite is `$\,{}^+$`.
+
+The error message will ask you to rerun `doconce` with
+`--mako_strict_undefined`, which will display the variable that
+is confusing Mako. However, do not continue to use
+`--mako_strict_undefined` while you are debugging because this
+variable will then always be undefined in that mode.
+Use `# #ifdef` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without `--mako_strict_undefined`).
+
#### Something goes wrong in the preprocessing step
You can examine `tmp_preprocess__filename` and `tmp_mako__filename`,
@@ -4109,6 +4151,15 @@
### Problems with HTML Output
+#### MathJax formulas are not properly rendered
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ * `[` and `]` brackets must sometimes be replaced by `\lbrack` and
`\rbrack`
+
#### How can I change the layout of the HTML page?
The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /doc/demos/manual/manual.mwiki Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.mwiki Fri Jun 28 09:22:02 2013
@@ -1,7 +1,7 @@
#TITLE (actually governed by the filename): Doconce Description
By '''Hans Petter Langtangen'''
-==== May 29, 2013 ====
+==== Jun 28, 2013 ====
<!-- lines beginning with # are doconce comment lines -->
<!-- (documents can also have mako comment lines) -->
@@ -549,7 +549,7 @@
Transformation of a Doconce document <code>mydoc.do.txt</code> to various
other
-formats applies the script <code>doconce format</code>:
+formats apply the script <code>doconce format</code>:
<syntaxhighlight lang="bash">
Terminal> doconce format format mydoc.do.txt
</syntaxhighlight>
@@ -2106,7 +2106,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with <code>===</code> heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in <code>html</code> output such that search engines can make use of
the them.
==== Bibliography ====
@@ -2275,6 +2279,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes <code>|</code> can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+<syntaxhighlight lang="text">
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+</syntaxhighlight>
+
Note that not all formats offer alignment of heading or entries
in tables (<code>rst</code> and <code>sphinx</code> are examples). Also
note that
Doconce tables are very simple: neither entries nor
@@ -2287,6 +2304,33 @@
where <code>X</code> is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the <code>doconce csv2table</code> utility:
+
+<syntaxhighlight lang="bash">
+Terminal> doconce csv2table somefile.csv > table.do.txt
+</syntaxhighlight>
+This is a quick way of writing tables. For example, we can
+write a text file <code>tmp.csv</code> with
+
+<syntaxhighlight lang="python">
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+</syntaxhighlight>
+Running <code>doconce csv2table tmp.csv</code> creates the table
+
+<syntaxhighlight lang="text">
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+</syntaxhighlight>
+
==== Exercises, Problems, Projects, and Examples ====
Doconce has special support for four types of "exercises", named
@@ -2686,13 +2730,6 @@
\end{align}
!et
</syntaxhighlight>
-Here is the result:
-
-:<math>
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, \\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. \end{align}
-</math>
The support of LaTeX mathematics varies among the formats:
@@ -2789,58 +2826,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-''Example.''
-Suppose we have the following commands in
-<code>newcommand_replace.tex</code>:
-
-<syntaxhighlight lang="text">
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-</syntaxhighlight>
-
-and these in <code>newcommands_keep.tex</code>:
-
-<syntaxhighlight lang="text">
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-</syntaxhighlight>
-
-The LaTeX block
-<syntaxhighlight lang="text">
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-</syntaxhighlight>
-will then be rendered to
-:<math>
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, \\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } \end{eqnarray}
-</math>
-in the current format.
==== Admonitions ====
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-<code>block</code>, <code>warning</code>, <code>notice</code>,
<code>hint</code>, <code>question</code>, and <code>summary</code>.
-The box is defined by begin and end tags such as <code>!bhint</code> and
<code>!ehint</code>.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading ''Hint'' (with number)
-appears, while outside exercises the <code>hint</code> environment gives a
-box with some admonition icon, text and/or colored background.)
+<code>block</code>, <code>warning</code>, <code>notice</code>,
<code>question</code>, and <code>summary</code>.
+The box is defined by begin and end tags such as <code>!bnotice</code> and
<code>!enotice</code>.
The title of the box is fully customizable.
Here are a few examples:
@@ -2850,9 +2848,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3253,7 +3251,9 @@
<!-- doconce-adjusted styles: easy to switch between styles since -->
<!-- font sizes are compatible -->
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
<syntaxhighlight lang="bash">
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3272,6 +3272,16 @@
==== LaTeX Beamer Slides ====
+Not yet written...
+
+==== Themes ====
+
+Four themes come with Doconce: <code>X_Y</code>, where <code>X</code> is
<code>blue</code> or <code>red</code>
+(the main color of the slides) and <code>Y</code> is
[http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf
<code>plain</code>]
+for simple layout and
+[http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf
<code>shadow</code>]
+for shadowed boxes and more visual structure in the slides.
+
== Mako Programming ==
The [http://docs.makotemplates.org/ Mako] templating engine is used
@@ -3281,6 +3291,18 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+{{mbox
+| type = warning
+| textstyle = font-size: 90%;
+| text = '''Warning.''' Unfortunately, the combination of Mako and LaTeX
mathematics may
+lead to problems because Mako applies syntax like <code>${var}</code> to
extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., <code>${\cal O}(\Delta x^2)$</code> which looks
like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+}}
+
==== The Basics of Mako ====
Just a preliminary sketch of some Mako code (next example is better!):
@@ -3455,6 +3477,15 @@
==== General Problems ====
+==== Spellcheck reports a lot of mistakes related LaTeX math ====
+
+The <code>doconce spellcheck</code> command should ignore LaTeX math, but
if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant <code>tmp_missing_*</code> file and search for the math
expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
==== Doconce aborts because of a syntax error that is not an error ====
Doconce searches for typical syntax errors and usually aborts the
@@ -3482,6 +3513,26 @@
to <code>'T < %.1f'</code> to avoid this confusion.
</ul>
+==== The Mako preprocessor claims a variable is undefined ====
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, <math>{\cal O}(\Delta x^2)</math> is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use <code>${</code> anywhere in LaTeX
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is <code>${}^+$</code> type of indication of
superscripts.
+A suggested rewrite is <code>$\,{}^+$</code>.
+
+The error message will ask you to rerun <code>doconce</code> with
+<code>--mako_strict_undefined</code>, which will display the variable that
+is confusing Mako. However, do not continue to use
+<code>--mako_strict_undefined</code> while you are debugging because this
+variable will then always be undefined in that mode.
+Use <code># #ifdef</code> directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without <code>--mako_strict_undefined</code>).
+
==== Something goes wrong in the preprocessing step ====
You can examine <code>tmp_preprocess__filename</code> and
<code>tmp_mako__filename</code>,
@@ -3870,6 +3921,17 @@
==== Problems with HTML Output ====
+==== MathJax formulas are not properly rendered ====
+
+Here are some common problems:
+
+
+<ul>
+ <li> Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+ <li> <code>[</code> and <code>]</code> brackets must sometimes be
replaced by <code>\lbrack</code> and <code>\rbrack</code>
+</ul>
+
==== How can I change the layout of the HTML page? ====
The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /doc/demos/manual/manual.p.tex Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.p.tex Fri Jun 28 09:22:02 2013
@@ -116,10 +116,11 @@
% #endif
% Hyperlinks in PDF:
+\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage[%
colorlinks=true,
- linkcolor=blue,
- urlcolor=blue,
+ linkcolor=linkcolor,
+ urlcolor=linkcolor,
citecolor=black,
filecolor=black,
%filecolor=blue,
@@ -168,10 +169,10 @@
% Admonition is an oval gray box
\newmdenv[
- backgroundcolor=gray!10, %% white with 10%% gray
+ backgroundcolor=gray!5, %% white with 5%% gray
skipabove=\topsep,
skipbelow=\topsep,
- outerlinewidth=0.5,
+ outerlinewidth=0,
leftmargin=0,
rightmargin=0,
roundcorner=5,
@@ -317,16 +318,16 @@
% #if LATEX_HEADING == "traditional"
-\date{May 29, 2013}
+\date{Jun 28, 2013}
\maketitle
% #elif LATEX_HEADING == "beamer"
-\date{May 29, 2013
+\date{Jun 28, 2013
% <titlepage figure>
}
% #elif LATEX_HEADING == "titlepage"
\ \\ [10mm]
-{\large\textsf{May 29, 2013}}
+{\large\textsf{Jun 28, 2013}}
\end{center}
\vfill
@@ -334,7 +335,7 @@
% #else
\begin{center}
-May 29, 2013
+Jun 28, 2013
\end{center}
\vspace{1cm}
@@ -896,7 +897,7 @@
\label{doconce2formats}
Transformation of a Doconce document \code{mydoc.do.txt} to various other
-formats applies the script \code{doconce format}:
+formats apply the script \code{doconce format}:
\bsys
Terminal> doconce format format mydoc.do.txt
\esys
@@ -1083,6 +1084,7 @@
code with MathJax
scripts so there is no support for mathematics in the discussion forum.
\end{graybox1admon}
+
\begin{graybox1admon}[Notice.]
Figure files must be uploaded to some web site and the filenames name must
be replaced by the relevant URL. This can be automatically edited:
@@ -1099,6 +1101,7 @@
# Paste mydoc2.html into a new blog page
\eshcod
\end{graybox1admon}
+
Blog posts at Google can also be published
\href{{http://support.google.com/blogger/bin/answer.py?hl=en&answer=41452}}{automatically
through email}.
A Python program can send the contents of the HTML file
to the blog's email address using the packages \code{smtplib} and
\code{email}.
@@ -2211,6 +2214,7 @@
becomes correct (sometimes a trial and error process - sticking to
very simple formatting usually avoids such problems).
\end{graybox1admon}
+
\paragraph{Links to Web Addresses.}
Web addresses with links are typeset as
\bccq
@@ -2530,7 +2534,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-{\LaTeX} is the output format).
+{\LaTeX} is the output format). For paragraphs with \code{===} heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in \code{html} output such that search engines can make use of the
them.
\subsection{Bibliography}
@@ -2571,6 +2579,7 @@
curly braces. You may need to edit your \textsc{Bib}\negthinspace{\TeX}
files to meet this
demand.
\end{graybox1admon}
+
The utility \code{doconce fix_bibtex4publish file.bib} fixes several known
issues with \textsc{Bib}\negthinspace{\TeX} files such that Publish has a
better chance of
accepting the entries. Run this utility first, then run Publish,
@@ -2695,6 +2704,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes \code{|} can also be inserted to indicate
vertical rules in {\LaTeX} tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+\bccq
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+\eccq
+
Note that not all formats offer alignment of heading or entries
in tables (\code{rst} and \code{sphinx} are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2707,6 +2729,33 @@
where \code{X} is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the \code{doconce csv2table} utility:
+
+\bsys
+Terminal> doconce csv2table somefile.csv > table.do.txt
+\esys
+This is a quick way of writing tables. For example, we can
+write a text file \code{tmp.csv} with
+
+\bdat
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+\edat
+Running \code{doconce csv2table tmp.csv} creates the table
+
+\bccq
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+\eccq
+
\subsection{Exercises, Problems, Projects, and Examples}
Doconce has special support for four types of "exercises", named
@@ -3108,12 +3157,6 @@
\end{align}
!et
\eccq
-Here is the result:
-
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, \label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. \label{myeq2}
-\end{align}
The support of {\LaTeX} mathematics varies among the formats:
@@ -3218,57 +3261,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-\paragraph{Example.}
-Suppose we have the following commands in
-\code{newcommand_replace.tex}:
-
-\blatexpro
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-\elatexpro
-
-and these in \code{newcommands_keep.tex}:
-
-\blatexpro
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-\elatexpro
-
-The {\LaTeX} block
-\bccq
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-\eccq
-will then be rendered to
-\beqa
-\x\cdot\normalvec &=& 0, \label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep \label{my:eq2}
-\eeqa
-in the current format.
\subsection{Admonitions}
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-\code{block}, \code{warning}, \code{notice}, \code{hint}, \code{question},
and \code{summary}.
-The box is defined by begin and end tags such as \code{!bhint} and
\code{!ehint}.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading \emph{Hint} (with number)
-appears, while outside exercises the \code{hint} environment gives a
-box with some admonition icon, text and/or colored background.)
+\code{block}, \code{warning}, \code{notice}, \code{question}, and
\code{summary}.
+The box is defined by begin and end tags such as \code{!bnotice} and
\code{!enotice}.
The title of the box is fully customizable.
Here are a few examples:
@@ -3278,9 +3283,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3304,17 +3309,21 @@
\begin{graybox1admon}[Warning.]
Here is a warning!
\end{graybox1admon}
+
\begin{graybox1admon}[Hint.]
This is a hint.
\end{graybox1admon}
+
\begin{graybox1admon}[This is a block.]
A block has never any icon.
\end{graybox1admon}
+
\begin{graybox1admon}[Going deeper.]
This is text meant to provide more details. The box has the
layout of the notice box, but a custom title, here "Going deeper".
\end{graybox1admon}
+
Finally some summary:
@@ -3322,6 +3331,7 @@
The main message is to utilize the admonition styles for
marking different parts of the text
\end{graybox1admon}
+
The layout of admonitions depend on the format.
In \code{rst} and \code{sphinx} one applies the native admonitions, but
in \code{sphinx} the \code{automake_sphinx.py} script manipulates the HTML
@@ -3592,6 +3602,7 @@
\subsection{Emacs Doconce Formatter}
\label{emacs:doconce}
+
The file
\href{{https://doconce.googlecode.com/hg/misc/.doconce-mode.el}}{.doconce-mode.el}
in the Doconce source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3697,7 +3708,9 @@
% doconce-adjusted styles: easy to switch between styles since
% font sizes are compatible
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
\bsys
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3716,6 +3729,15 @@
\noindent
\subsection{{\LaTeX} Beamer Slides}
+
+Not yet written...
+
+\paragraph{Themes.}
+Four themes come with Doconce: \code{X_Y}, where \code{X} is \code{blue}
or \code{red}
+(the main color of the slides) and \code{Y} is
\href{{http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf}}{\nolinkurl{plain}}
+for simple layout and
+\href{{http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf}}{\nolinkurl{shadow}}
+for shadowed boxes and more visual structure in the slides.
\section{Mako Programming}
@@ -3726,6 +3748,16 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+\begin{graybox1admon}[Warning.]
+Unfortunately, the combination of Mako and {\LaTeX} mathematics may
+lead to problems because Mako applies syntax like \code{${var}} to extract
+variables or call functions, while {\LaTeX} mathematics sometimes applies
+the same syntax, e.g., \code{${\cal O}(\Delta x^2)$} which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+\end{graybox1admon}
+
\subsection{The Basics of Mako}
Just a preliminary sketch of some Mako code (next example is better!):
@@ -3900,6 +3932,14 @@
\subsection{General Problems}
+
+\paragraph{Spellcheck reports a lot of mistakes related {\LaTeX} math.}
+The \code{doconce spellcheck} command should ignore {\LaTeX} math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant \code{tmp_missing_*} file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
\paragraph{Doconce aborts because of a syntax error that is not an error.}
Doconce searches for typical syntax errors and usually aborts the
@@ -3925,6 +3965,25 @@
\end{itemize}
\noindent
+\paragraph{The Mako preprocessor claims a variable is undefined.}
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired {\LaTeX} syntax.
+For example, ${\cal O}(\Delta x^2)$ is valid {\LaTeX}, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use \code{${} anywhere in {\LaTeX}
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is \code{${}^+$} type of indication of superscripts.
+A suggested rewrite is \code{$\,{}^+$}.
+
+The error message will ask you to rerun \code{doconce} with
+\code{--mako_strict_undefined}, which will display the variable that
+is confusing Mako. However, do not continue to use
+\code{--mako_strict_undefined} while you are debugging because this
+variable will then always be undefined in that mode.
+Use \code{# #ifdef} directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without \code{--mako_strict_undefined}).
+
\paragraph{Something goes wrong in the preprocessing step.}
You can examine \code{tmp_preprocess__filename} and
\code{tmp_mako__filename},
where \code{filename} is the complete name of the Doconce file, to see
@@ -4157,7 +4216,7 @@
When this package is included, \code{latex} or \code{pdflatex} runs the
\code{pygmentize} program and the \code{shell-escape} option is required.
-\paragraph{Why are the {\LaTeX} section headings smaller than normal?.}
+\paragraph{Why are the {\LaTeX} section headings smaller than normal?}
Doconce inserts a special command to make the headings
more compact:
@@ -4176,7 +4235,7 @@
by replacing \code{[compact]} by \code{[compact,small]} as parameter
specification
for \code{titlesec}.
-\paragraph{Can I have {\LaTeX} figures with shadows?.}
+\paragraph{Can I have {\LaTeX} figures with shadows?}
This is easy by including the \code{fancybox} and \code{graphicx} packages
and wrapping all \code{\includegraphics} in a shadow box:
@@ -4188,7 +4247,7 @@
'\\shadowbox{\g<1>}' mydoc.p.tex
\esys
-\paragraph{How can I use my fancy {\LaTeX} environments?.}
+\paragraph{How can I use my fancy {\LaTeX} environments?}
See Section~\ref{manual:theorem:envir} for how to make a custom
theorem environment also in Doconce, without using implementations
restricted to {\LaTeX}.
@@ -4276,7 +4335,18 @@
\subsection{Problems with HTML Output}
-\paragraph{How can I change the layout of the HTML page?.}
+\paragraph{MathJax formulas are not properly rendered.}
+Here are some common problems:
+
+\begin{itemize}
+ \item Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ \item \code{[} and \code{]} brackets must sometimes be replaced by
\code{\lbrack} and \code{\rbrack}
+\end{itemize}
+
+\noindent
+\paragraph{How can I change the layout of the HTML page?}
The easiest way is to edit the HTML style or the HTML code directly.
However, those edits are overwritten the next time you compile the
Doconce document to HTML. The edits should therefore be automated
@@ -4313,7 +4383,7 @@
use the \code{sphinx} format and one its many themes.
-\paragraph{Why do figures look ugly when using HTML templates?.}
+\paragraph{Why do figures look ugly when using HTML templates?}
The HTML header that Doconce generates contain special styles for
figure captions and the horizontal rule above figures. When using
templates these styles are not defined, resulting in a rule that
=======================================
--- /doc/demos/manual/manual.pdf Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.pdf Fri Jun 28 09:22:02 2013
Binary file, no diff available.
=======================================
--- /doc/demos/manual/manual.rst Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.rst Fri Jun 28 09:22:02 2013
@@ -5,7 +5,7 @@
===================
:Author: Hans Petter Langtangen
-:Date: May 29, 2013
+:Date: Jun 28, 2013
.. lines beginning with # are doconce comment lines
@@ -598,7 +598,7 @@
=============================
Transformation of a Doconce document ``mydoc.do.txt`` to various other
-formats applies the script ``doconce format``::
+formats apply the script ``doconce format``::
Terminal> doconce format format mydoc.do.txt
@@ -2271,7 +2271,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with ``===`` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in ``html`` output such that search engines can make use of the them.
Bibliography (2)
-----------------
@@ -2450,6 +2454,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes ``|`` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like::
+
+
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+
+
Note that not all formats offer alignment of heading or entries
in tables (``rst`` and ``sphinx`` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2462,6 +2479,33 @@
where ``X`` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the ``doconce csv2table`` utility::
+
+
+ Terminal> doconce csv2table somefile.csv > table.do.txt
+
+This is a quick way of writing tables. For example, we can
+write a text file ``tmp.csv`` with::
+
+
+ time, velocity, acceleration
+ 0.0, 1.4186, -5.01
+ 2.0, 1.376512, 11.919
+ 4.0, 1.1E+1, 14.717624
+
+Running ``doconce csv2table tmp.csv`` creates the table::
+
+
+ |------c--------------c--------------c-------|
+ | time | velocity | acceleration |
+ |------c--------------c--------------c-------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------------------|
+
+
Exercises, Problems, Projects, and Examples
-------------------------------------------
@@ -2883,13 +2927,6 @@
\end{align}
!et
-Here is the result::
-
- \begin{align}
- {\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
- {\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
- \end{align}
-
The support of LaTeX mathematics varies among the formats:
@@ -2991,61 +3028,21 @@
newcommands in the ``newcommands*.tex`` files *must* appear on a single
line (multi-line newcommands are too hard to parse with regular
expressions).
-
-*Example.* Suppose we have the following commands in
-``newcommand_replace.tex``::
-
-
- \newcommand{\beqa}{\begin{eqnarray}}
- \newcommand{\eeqa}{\end{eqnarray}}
- \newcommand{\ep}{\thinspace . }
- \newcommand{\uvec}{\vec u}
- \newcommand{\Q}{\pmb{Q}}
-and these in ``newcommands_keep.tex``::
-
-
- \newcommand{\x}{\pmb{x}}
- \newcommand{\normalvec}{\pmb{n}}
- \newcommand{\Ddt}[1]{\frac{D#1}{dt}}
- \newcommand{\half}{\frac{1}{2}}
-
-
-The LaTeX block::
-
-
- \beqa
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{\uvec} &=& \Q \ep label{my:eq2}
- \eeqa
-
-will then be rendered to::
-
- \begin{eqnarray}
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
- \end{eqnarray}
-
-in the current format.
-
Admonitions
-----------
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-``block``, ``warning``, ``notice``, ``hint``, ``question``, and
``summary``.
-The box is defined by begin and end tags such as ``!bhint`` and ``!ehint``.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the ``hint`` environment gives a
-box with some admonition icon, text and/or colored background.)
+``block``, ``warning``, ``notice``, ``question``, and ``summary``.
+The box is defined by begin and end tags such as ``!bnotice`` and
``!enotice``.
The title of the box is fully customizable.
Here are a few examples::
@@ -3055,9 +3052,9 @@
Here is a warning!
!ewarning
- !bhint
+ !bnotice Hint
This is a hint.
- !ehint
+ !enotice
!bblock This is a block.
A block has never any icon.
@@ -3082,7 +3079,8 @@
Here is a warning!
-.. hint::
+.. admonition:: Hint
+
This is a hint.
@@ -3376,6 +3374,7 @@
Emacs Doconce Formatter
-----------------------
+
The file `.doconce-mode.el
<https://doconce.googlecode.com/hg/misc/.doconce-mode.el>`_ in the Doconce
source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3476,7 +3475,9 @@
.. font sizes are compatible
-Text is missing... Just a very preliminary sketch of commands::
+Not yet written...
+
+Just a very preliminary sketch of commands::
Terminal> doconce format html myslides \
@@ -3497,6 +3498,17 @@
LaTeX Beamer Slides
-------------------
+Not yet written...
+
+Themes
+~~~~~~
+
+Four themes come with Doconce: ``X_Y``, where ``X`` is ``blue`` or ``red``
+(the main color of the slides) and ``Y`` is `plain
<http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf>`_
+for simple layout and
+`shadow
<http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf>`_
+for shadowed boxes and more visual structure in the slides.
+
Mako Programming
================
@@ -3507,6 +3519,16 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+.. warning::
+ Unfortunately, the combination of Mako and LaTeX mathematics may
+ lead to problems because Mako applies syntax like ``${var}`` to extract
+ variables or call functions, while LaTeX mathematics sometimes applies
+ the same syntax, e.g., ``${\cal O}(\Delta x^2)$`` which looks like a
+ Mako function call. This problem can give rise to strange error
+ messages from Mako, usually that a variable is not defined.
+
+
The Basics of Mako
------------------
@@ -3691,6 +3713,16 @@
General Problems
----------------
+Spellcheck reports a lot of mistakes related LaTeX math
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``doconce spellcheck`` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant ``tmp_missing_*`` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
Doconce aborts because of a syntax error that is not an error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3718,6 +3750,27 @@
* Strings with ``'T<%.1f'`` look as openings of Mako blocks (``<%``);
change
to ``'T < %.1f'`` to avoid this confusion.
+The Mako preprocessor claims a variable is undefined
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, {\cal O}(\Delta x^2) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use ``${`` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is ``${}^+$`` type of indication of superscripts.
+A suggested rewrite is ``$\,{}^+$``.
+
+The error message will ask you to rerun ``doconce`` with
+``--mako_strict_undefined``, which will display the variable that
+is confusing Mako. However, do not continue to use
+``--mako_strict_undefined`` while you are debugging because this
+variable will then always be undefined in that mode.
+Use ``# #ifdef`` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without ``--mako_strict_undefined``).
+
Something goes wrong in the preprocessing step
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4159,6 +4212,16 @@
Problems with HTML Output
-------------------------
+MathJax formulas are not properly rendered
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ * ``[`` and ``]`` brackets must sometimes be replaced by ``\lbrack`` and
``\rbrack``
+
How can I change the layout of the HTML page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================
--- /doc/demos/manual/manual.rst.html Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.rst.html Fri Jun 28 09:22:02 2013
@@ -327,7 +327,7 @@
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td
class="field-body">Hans Petter Langtangen</td>
</tr>
-<tr class="field"><th class="field-name">Date:</th><td
class="field-body">May 29, 2013</td>
+<tr class="field"><th class="field-name">Date:</th><td
class="field-body">Jun 28, 2013</td>
</tr>
</tbody>
</table>
@@ -846,7 +846,7 @@
<div class="section" id="from-doconce-to-other-formats">
<span id="doconce2formats"></span><h1>From Doconce to Other Formats</h1>
<p>Transformation of a Doconce document <tt class="docutils
literal">mydoc.do.txt</tt> to various other
-formats applies the script <tt class="docutils literal">doconce
format</tt>:</p>
+formats apply the script <tt class="docutils literal">doconce
format</tt>:</p>
<pre class="literal-block">
Terminal> doconce format format mydoc.do.txt
</pre>
@@ -2246,7 +2246,10 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).</p>
+LaTeX is the output format). For paragraphs with <tt class="docutils
literal">===</tt> heading,
+the index keywords should be placed above the heading.</p>
+<p>The keywords in the index are automatically placed in a meta
+tag in <tt class="docutils literal">html</tt> output such that search
engines can make use of the them.</p>
</div>
<div class="section" id="bibliography-2">
<h2>Bibliography (2)</h2>
@@ -2422,7 +2425,18 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes <tt class="docutils literal">|</tt> can also be
inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
-Note that not all formats offer alignment of heading or entries
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like:</p>
+<pre class="literal-block">
+|--c--------c-----------c--------|
+|time | velocity | acceleration |
+|--l--------r-----------r--------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------|
+</pre>
+<p>Note that not all formats offer alignment of heading or entries
in tables (<tt class="docutils literal">rst</tt> and <tt class="docutils
literal">sphinx</tt> are examples). Also note that
Doconce tables are very simple: neither entries nor
headings can span several columns or rows. When that functionality
@@ -2432,6 +2446,29 @@
makes Doconce dump each table to CSV format in a file <tt class="docutils
literal">table_X.csv</tt>,
where <tt class="docutils literal">X</tt> is the table number. This
feature makes it easy to
load tables into spreadsheet programs for further analysis.</p>
+<p>Data in CSV format can be transformed to Doconce table format
+by the <tt class="docutils literal">doconce csv2table</tt> utility:</p>
+<pre class="literal-block">
+Terminal> doconce csv2table somefile.csv > table.do.txt
+</pre>
+<p>This is a quick way of writing tables. For example, we can
+write a text file <tt class="docutils literal">tmp.csv</tt> with:</p>
+<pre class="literal-block">
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+</pre>
+<p>Running <tt class="docutils literal">doconce csv2table tmp.csv</tt>
creates the table:</p>
+<pre class="literal-block">
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+</pre>
</div>
<div class="section" id="exercises-problems-projects-and-examples">
<h2>Exercises, Problems, Projects, and Examples</h2>
@@ -2800,13 +2837,6 @@
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
\end{align}
!et
-</pre>
-<p>Here is the result:</p>
-<pre class="literal-block">
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
-\end{align}
</pre>
<p>The support of LaTeX mathematics varies among the formats:</p>
<blockquote>
@@ -2897,53 +2927,18 @@
newcommands in the <tt class="docutils literal"><span
class="pre">newcommands*.tex</span></tt> files <em>must</em> appear on a
single
line (multi-line newcommands are too hard to parse with regular
expressions).</p>
-<p><em>Example.</em> Suppose we have the following commands in
-<tt class="docutils literal">newcommand_replace.tex</tt>:</p>
-<pre class="literal-block">
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-</pre>
-<p>and these in <tt class="docutils literal">newcommands_keep.tex</tt>:</p>
-<pre class="literal-block">
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-</pre>
-<p>The LaTeX block:</p>
-<pre class="literal-block">
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-</pre>
-<p>will then be rendered to:</p>
-<pre class="literal-block">
-\begin{eqnarray}
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
-\end{eqnarray}
-</pre>
-<p>in the current format.</p>
</div>
<div class="section" id="admonitions">
<h2>Admonitions</h2>
<p>Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.</p>
<p>The following admonition environments are available:
-<tt class="docutils literal">block</tt>, <tt class="docutils
literal">warning</tt>, <tt class="docutils literal">notice</tt>, <tt
class="docutils literal">hint</tt>, <tt class="docutils
literal">question</tt>, and <tt class="docutils literal">summary</tt>.
-The box is defined by begin and end tags such as <tt class="docutils
literal">!bhint</tt> and <tt class="docutils literal">!ehint</tt>.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading <em>Hint</em> (with number)
-appears, while outside exercises the <tt class="docutils
literal">hint</tt> environment gives a
-box with some admonition icon, text and/or colored background.)
+<tt class="docutils literal">block</tt>, <tt class="docutils
literal">warning</tt>, <tt class="docutils literal">notice</tt>, <tt
class="docutils literal">question</tt>, and <tt class="docutils
literal">summary</tt>.
+The box is defined by begin and end tags such as <tt class="docutils
literal">!bnotice</tt> and <tt class="docutils literal">!enotice</tt>.
The title of the box is fully customizable.</p>
<p>Here are a few examples:</p>
<pre class="literal-block">
@@ -2951,9 +2946,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -2976,7 +2971,7 @@
<p class="first admonition-title">Warning</p>
<p class="last">Here is a warning!</p>
</div>
-<div class="hint">
+<div class="admonition-hint admonition">
<p class="first admonition-title">Hint</p>
<p class="last">This is a hint.</p>
</div>
@@ -3348,7 +3343,8 @@
<h2>HTML5 Slides</h2>
<!-- doconce-adjusted styles: easy to switch between styles since -->
<!-- font sizes are compatible -->
-<p>Text is missing... Just a very preliminary sketch of commands:</p>
+<p>Not yet written...</p>
+<p>Just a very preliminary sketch of commands:</p>
<pre class="literal-block">
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3369,12 +3365,21 @@
</div>
<div class="section" id="latex-beamer-slides">
<h2>LaTeX Beamer Slides</h2>
+<p>Not yet written...</p>
+<div class="section" id="themes">
+<h3>Themes</h3>
+<p>Four themes come with Doconce: <tt class="docutils literal">X_Y</tt>,
where <tt class="docutils literal">X</tt> is <tt class="docutils
literal">blue</tt> or <tt class="docutils literal">red</tt>
+(the main color of the slides) and <tt class="docutils literal">Y</tt> is
<a class="reference external"
href="http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf">plain</a>
+for simple layout and
+<a class="reference external"
href="http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf">shadow</a>
+for shadowed boxes and more visual structure in the slides.</p>
+</div>
</div>
</div>
<div class="section" id="mako-programming">
<h1>Mako Programming</h1>
<div class="system-message">
-<p class="system-message-title">System Message: WARNING/2 (<tt
class="docutils">manual.rst</tt>, line 3501); <em><a
href="#id15">backlink</a></em></p>
+<p class="system-message-title">System Message: WARNING/2 (<tt
class="docutils">manual.rst</tt>, line 3513); <em><a
href="#id15">backlink</a></em></p>
Duplicate explicit target name: "mako".</div>
<p>The <a class="reference external"
href="http://docs.makotemplates.org/">Mako</a> templating engine is used
as preprocessor for Doconce documents, but the <a class="reference
external" href="http://code.google.com/p/preprocess">Preprocess</a> is run
prior to Mako and is recommended for
@@ -3382,6 +3387,15 @@
sufficient for if-else tests to steer which parts of the text that
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.</p>
+<div class="warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Unfortunately, the combination of Mako and LaTeX
mathematics may
+lead to problems because Mako applies syntax like <tt class="docutils
literal">${var}</tt> to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., <tt class="docutils literal"><span
class="pre">${\cal</span> <span class="pre">O}(\Delta</span> x^2)$</tt>
which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.</p>
+</div>
<div class="section" id="the-basics-of-mako">
<h2>The Basics of Mako</h2>
<p>Just a preliminary sketch of some Mako code (next example is
better!):</p>
@@ -3549,6 +3563,15 @@
</div>
<div class="section" id="general-problems">
<h2>General Problems</h2>
+<div class="section"
id="spellcheck-reports-a-lot-of-mistakes-related-latex-math">
+<h3>Spellcheck reports a lot of mistakes related LaTeX math</h3>
+<p>The <tt class="docutils literal">doconce spellcheck</tt> command should
ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant <tt class="docutils literal">tmp_missing_*</tt> file and search
for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.</p>
+</div>
<div class="section"
id="doconce-aborts-because-of-a-syntax-error-that-is-not-an-error">
<h3>Doconce aborts because of a syntax error that is not an error</h3>
<p>Doconce searches for typical syntax errors and usually aborts the
@@ -3576,6 +3599,25 @@
</ul>
</blockquote>
</div>
+<div class="section"
id="the-mako-preprocessor-claims-a-variable-is-undefined">
+<h3>The Mako preprocessor claims a variable is undefined</h3>
+<p>Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, {cal O}(Delta x^2) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use <tt class="docutils literal">${</tt>
anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is <tt class="docutils literal"><span
class="pre">${}^+$</span></tt> type of indication of superscripts.
+A suggested rewrite is <tt class="docutils literal"><span
class="pre">$\,{}^+$</span></tt>.</p>
+<p>The error message will ask you to rerun <tt class="docutils
literal">doconce</tt> with
+<tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt>, which will display the
variable that
+is confusing Mako. However, do not continue to use
+<tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt> while you are debugging
because this
+variable will then always be undefined in that mode.
+Use <tt class="docutils literal"># #ifdef</tt> directives to comment out
large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without <tt class="docutils literal"><span
class="pre">--mako_strict_undefined</span></tt>).</p>
+</div>
<div class="section" id="something-goes-wrong-in-the-preprocessing-step">
<h3>Something goes wrong in the preprocessing step</h3>
<p>You can examine <tt class="docutils
literal">tmp_preprocess__filename</tt> and <tt class="docutils
literal">tmp_mako__filename</tt>,
@@ -3952,6 +3994,17 @@
</div>
<div class="section" id="problems-with-html-output">
<h2>Problems with HTML Output</h2>
+<div class="section" id="mathjax-formulas-are-not-properly-rendered">
+<h3>MathJax formulas are not properly rendered</h3>
+<p>Here are some common problems:</p>
+<blockquote>
+<ul class="simple">
+<li>Two equations cannot have identical label (this error often arises
+from copying and pasting equations)</li>
+<li><tt class="docutils literal">[</tt> and <tt class="docutils
literal">]</tt> brackets must sometimes be replaced by <tt class="docutils
literal">\lbrack</tt> and <tt class="docutils literal">\rbrack</tt></li>
+</ul>
+</blockquote>
+</div>
<div class="section" id="how-can-i-change-the-layout-of-the-html-page">
<h3>How can I change the layout of the HTML page?</h3>
<p>The easiest way is to edit the HTML style or the HTML code directly.
=======================================
--- /doc/demos/manual/manual.rst.pdf Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.rst.pdf Fri Jun 28 09:22:02 2013
Binary file, no diff available.
=======================================
--- /doc/demos/manual/manual.rst.tex Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.rst.tex Fri Jun 28 09:22:02 2013
@@ -82,7 +82,7 @@
Hans Petter Langtangen
\item[{Date:}]
-May 29, 2013
+Jun 28, 2013
\end{DUfieldlist}
@@ -899,7 +899,7 @@
}
Transformation of a Doconce document \texttt{mydoc.do.txt} to various other
-formats applies the script \texttt{doconce format}:
+formats apply the script \texttt{doconce format}:
%
\begin{quote}{\ttfamily \raggedright \noindent
Terminal>~doconce~format~format~mydoc.do.txt
@@ -2980,7 +2980,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with \texttt{===} heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in \texttt{html} output such that search engines can make use of the
them.
%___________________________________________________________________________
@@ -3269,6 +3273,20 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes \texttt{|} can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like:
+%
+\begin{quote}{\ttfamily \raggedright \noindent
+|
-{}-c-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-|
\\
+|time~~|~velocity~|~acceleration~|\\
+|
-{}-l-{}-{}-{}-{}-{}-{}-{}-r-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-r-{}-{}-{}-{}-{}-{}-{}-|
\\
+|~0.0~~|~1.4186~~~|~-5.01~~~~~~~~|\\
+|~2.0~~|~1.376512~|~11.919~~~~~~~|\\
+|~4.0~~|~1.1E+1~~~|~14.717624~~~~|\\
+|
-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-|
+}
+\end{quote}
+
Note that not all formats offer alignment of heading or entries
in tables (\texttt{rst} and \texttt{sphinx} are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -3281,6 +3299,38 @@
where \texttt{X} is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the \texttt{doconce csv2table} utility:
+%
+\begin{quote}{\ttfamily \raggedright \noindent
+Terminal>~doconce~csv2table~somefile.csv~>~table.do.txt
+}
+\end{quote}
+
+This is a quick way of writing tables. For example, we can
+write a text file \texttt{tmp.csv} with:
+%
+\begin{quote}{\ttfamily \raggedright \noindent
+time,~velocity,~acceleration\\
+0.0,~1.4186,~-5.01\\
+2.0,~1.376512,~11.919\\
+4.0,~1.1E+1,~14.717624
+}
+\end{quote}
+
+Running \texttt{doconce csv2table tmp.csv} creates the table:
+%
+\begin{quote}{\ttfamily \raggedright \noindent
+|
-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-|
\\
+|~time~~~~~~~~~|~velocity~~~~~|~acceleration~|\\
+|
-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-c-{}-{}-{}-{}-{}-{}-|
\\
+|~0.0~~~~~~~~~~|~1.4186~~~~~~~|~-5.01~~~~~~~~|\\
+|~2.0~~~~~~~~~~|~1.376512~~~~~|~11.919~~~~~~~|\\
+|~4.0~~~~~~~~~~|~1.1E+1~~~~~~~|~14.717624~~~~|\\
+|
-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-|
+}
+\end{quote}
+
%___________________________________________________________________________
@@ -3736,16 +3786,6 @@
!et
}
\end{quote}
-
-Here is the result:
-%
-\begin{quote}{\ttfamily \raggedright \noindent
-\textbackslash{}begin\{align\}\\
-\{\textbackslash{}partial~u\textbackslash{}over\textbackslash{}partial~t\}~\&=~\textbackslash{}nabla\textasciicircum{}2~u~+~f,~label\{myeq1\}\textbackslash{}\textbackslash{}\\
-\{\textbackslash{}partial~v\textbackslash{}over\textbackslash{}partial~t\}~\&=~\textbackslash{}nabla\textbackslash{}cdot(q(u)\textbackslash{}nabla~v)~+~g.~label\{myeq2\}\\
-\textbackslash{}end\{align\}
-}
-\end{quote}
The support of LaTeX mathematics varies among the formats:
%
@@ -3878,50 +3918,6 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-\emph{Example.} Suppose we have the following commands in
-\texttt{newcommand\_replace.tex}:
-%
-\begin{quote}{\ttfamily \raggedright \noindent
-\textbackslash{}newcommand\{\textbackslash{}beqa\}\{\textbackslash{}begin\{eqnarray\}\}\\
-\textbackslash{}newcommand\{\textbackslash{}eeqa\}\{\textbackslash{}end\{eqnarray\}\}\\
-\textbackslash{}newcommand\{\textbackslash{}ep\}\{\textbackslash{}thinspace~.~\}\\
-\textbackslash{}newcommand\{\textbackslash{}uvec\}\{\textbackslash{}vec~u\}\\
-\textbackslash{}newcommand\{\textbackslash{}Q\}\{\textbackslash{}pmb\{Q\}\}
-}
-\end{quote}
-
-and these in \texttt{newcommands\_keep.tex}:
-%
-\begin{quote}{\ttfamily \raggedright \noindent
-\textbackslash{}newcommand\{\textbackslash{}x\}\{\textbackslash{}pmb\{x\}\}\\
-\textbackslash{}newcommand\{\textbackslash{}normalvec\}\{\textbackslash{}pmb\{n\}\}\\
-\textbackslash{}newcommand\{\textbackslash{}Ddt\}{[}1{]}\{\textbackslash{}frac\{D\#1\}\{dt\}\}\\
-\textbackslash{}newcommand\{\textbackslash{}half\}\{\textbackslash{}frac\{1\}\{2\}\}
-}
-\end{quote}
-
-The LaTeX block:
-%
-\begin{quote}{\ttfamily \raggedright \noindent
-\textbackslash{}beqa\\
-\textbackslash{}x\textbackslash{}cdot\textbackslash{}normalvec~\&=\&~0,~label\{my:eq1\}\textbackslash{}\textbackslash{}\\
-\textbackslash{}Ddt\{\textbackslash{}uvec\}~\&=\&~\textbackslash{}Q~\textbackslash{}ep~~~label\{my:eq2\}\\
-\textbackslash{}eeqa
-}
-\end{quote}
-
-will then be rendered to:
-%
-\begin{quote}{\ttfamily \raggedright \noindent
-\textbackslash{}begin\{eqnarray\}\\
-\textbackslash{}x\textbackslash{}cdot\textbackslash{}normalvec~\&=\&~0,~label\{my:eq1\}\textbackslash{}\textbackslash{}\\
-\textbackslash{}Ddt\{\{\textbackslash{}vec~u\}\}~\&=\&~\textbackslash{}pmb\{Q\}~\{\textbackslash{}thinspace~.~\}~~~label\{my:eq2\}\\
-\textbackslash{}end\{eqnarray\}
-}
-\end{quote}
-
-in the current format.
-
%___________________________________________________________________________
@@ -3932,19 +3928,15 @@
}
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-\texttt{block}, \texttt{warning}, \texttt{notice}, \texttt{hint},
\texttt{question}, and \texttt{summary}.
-The box is defined by begin and end tags such as \texttt{!bhint} and
\texttt{!ehint}.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading \emph{Hint} (with number)
-appears, while outside exercises the \texttt{hint} environment gives a
-box with some admonition icon, text and/or colored background.)
+\texttt{block}, \texttt{warning}, \texttt{notice}, \texttt{question}, and
\texttt{summary}.
+The box is defined by begin and end tags such as \texttt{!bnotice} and
\texttt{!enotice}.
The title of the box is fully customizable.
Here are a few examples:
@@ -3954,9 +3946,9 @@
Here~is~a~warning!\\
!ewarning\\
~\\
-!bhint\\
+!bnotice~Hint\\
This~is~a~hint.\\
-!ehint\\
+!enotice\\
~\\
!bblock~This~is~a~block.\\
A~block~has~never~any~icon.\\
@@ -3984,8 +3976,8 @@
Here is a warning!
}
-\DUadmonition[hint]{
-\DUtitle[hint]{Hint}
+\DUadmonition[admonition-hint]{
+\DUtitle[admonition-hint]{Hint}
This is a hint.
}
@@ -4557,7 +4549,9 @@
% font sizes are compatible
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
%
\begin{quote}{\ttfamily \raggedright \noindent
Terminal>~doconce~format~html~myslides~\textbackslash{}\\
@@ -4599,6 +4593,23 @@
\label{latex-beamer-slides}%
}
+Not yet written...
+
+
+%___________________________________________________________________________
+
+\subsubsection*{\phantomsection%
+ Themes%
+ \addcontentsline{toc}{subsubsection}{Themes}%
+ \label{themes}%
+}
+
+Four themes come with Doconce: \texttt{X\_Y}, where \texttt{X} is
\texttt{blue} or \texttt{red}
+(the main color of the slides) and \texttt{Y} is
\href{http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf}{plain}
+for simple layout and
+\href{http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf}{shadow}
+for shadowed boxes and more visual structure in the slides.
+
%___________________________________________________________________________
@@ -4612,7 +4623,7 @@
\DUtitle[system-message]{system-message}
-{\color{red}WARNING/2} in \texttt{manual.rst}, line~3501
+{\color{red}WARNING/2} in \texttt{manual.rst}, line~3513
\hyperlink{id15}{
Duplicate explicit target name: ``mako''.
@@ -4625,6 +4636,17 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+\DUadmonition[warning]{
+\DUtitle[warning]{Warning}
+
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like \texttt{\$\{var\}} to
extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., \texttt{\$\{\textbackslash{}cal
O\}(\textbackslash{}Delta x\textasciicircum{}2)\$} which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+}
+
%___________________________________________________________________________
@@ -4843,6 +4865,22 @@
\addcontentsline{toc}{subsection}{General Problems}%
\label{general-problems}%
}
+
+
+%___________________________________________________________________________
+
+\subsubsection*{\phantomsection%
+ Spellcheck reports a lot of mistakes related LaTeX math%
+ \addcontentsline{toc}{subsubsection}{Spellcheck reports a lot of
mistakes related LaTeX math}%
+ \label{spellcheck-reports-a-lot-of-mistakes-related-latex-math}%
+}
+
+The \texttt{doconce spellcheck} command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant \texttt{tmp\_missing\_*} file and search for the math expressions
that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
%___________________________________________________________________________
@@ -4896,6 +4934,33 @@
\end{itemize}
\end{quote}
+
+
+%___________________________________________________________________________
+
+\subsubsection*{\phantomsection%
+ The Mako preprocessor claims a variable is undefined%
+ \addcontentsline{toc}{subsubsection}{The Mako preprocessor claims a
variable is undefined}%
+ \label{the-mako-preprocessor-claims-a-variable-is-undefined}%
+}
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, \{cal O\}(Delta x\textasciicircum{}2) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use \texttt{\$\{} anywhere in LaTeX
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is \texttt{\$\{\}\textasciicircum{}+\$} type of
indication of superscripts.
+A suggested rewrite is
\texttt{\$\textbackslash{},\{\}\textasciicircum{}+\$}.
+
+The error message will ask you to rerun \texttt{doconce} with
+\texttt{-{}-mako\_strict\_undefined}, which will display the variable that
+is confusing Mako. However, do not continue to use
+\texttt{-{}-mako\_strict\_undefined} while you are debugging because this
+variable will then always be undefined in that mode.
+Use \texttt{\# \#ifdef} directives to comment out large portions of
+the text and apply a ``bisection'' procedure to locate where
+the Mako problem is (without \texttt{-{}-mako\_strict\_undefined}).
%___________________________________________________________________________
@@ -5620,6 +5685,30 @@
\addcontentsline{toc}{subsection}{Problems with HTML Output}%
\label{problems-with-html-output}%
}
+
+
+%___________________________________________________________________________
+
+\subsubsection*{\phantomsection%
+ MathJax formulas are not properly rendered%
+ \addcontentsline{toc}{subsubsection}{MathJax formulas are not properly
rendered}%
+ \label{mathjax-formulas-are-not-properly-rendered}%
+}
+
+Here are some common problems:
+%
+\begin{quote}
+%
+\begin{itemize}
+
+\item Two equations cannot have identical label (this error often arises
+from copying and pasting equations)
+
+\item \texttt{{[}} and \texttt{{]}} brackets must sometimes be replaced by
\texttt{\textbackslash{}lbrack} and \texttt{\textbackslash{}rbrack}
+
+\end{itemize}
+
+\end{quote}
%___________________________________________________________________________
=======================================
--- /doc/demos/manual/manual.sphinx.rst Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.sphinx.rst Fri Jun 28 09:22:02 2013
@@ -5,7 +5,7 @@
===================
:Author: Hans Petter Langtangen
-:Date: May 29, 2013
+:Date: Jun 28, 2013
.. lines beginning with # are doconce comment lines
@@ -658,7 +658,7 @@
=============================
Transformation of a Doconce document ``mydoc.do.txt`` to various other
-formats applies the script ``doconce format``:
+formats apply the script ``doconce format``:
.. code-block:: console
@@ -2348,7 +2348,7 @@
(the label appears in the figure caption in the source code of this
document).
Additional references to the sections :ref:`mathtext`
and :ref:`newcommands` are
nice to demonstrate, as well as a reference to equations,
-say :eq:`myeq1`-:eq:`myeq2`. A comparison of the output and
+say (:ref:`myeq1`)-(:ref:`myeq2`). A comparison of the output and
the source of this document illustrates how labels and references
are handled by the format in question.
@@ -2500,7 +2500,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with ``===`` heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in ``html`` output such that search engines can make use of the them.
Bibliography (2)
-----------------
@@ -2696,6 +2700,22 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes ``|`` can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+
+.. code-block:: text
+
+
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+
+
Note that not all formats offer alignment of heading or entries
in tables (``rst`` and ``sphinx`` are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2708,6 +2728,40 @@
where ``X`` is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the ``doconce csv2table`` utility:
+
+
+.. code-block:: console
+
+ Terminal> doconce csv2table somefile.csv > table.do.txt
+
+This is a quick way of writing tables. For example, we can
+write a text file ``tmp.csv`` with
+
+
+.. code-block:: python
+
+ time, velocity, acceleration
+ 0.0, 1.4186, -5.01
+ 2.0, 1.376512, 11.919
+ 4.0, 1.1E+1, 14.717624
+
+Running ``doconce csv2table tmp.csv`` creates the table
+
+
+.. code-block:: text
+
+
+ |------c--------------c--------------c-------|
+ | time | velocity | acceleration |
+ |------c--------------c--------------c-------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------------------|
+
+
Exercises, Problems, Projects, and Examples
-------------------------------------------
@@ -3160,23 +3214,6 @@
\end{align}
!et
-Here is the result:
-
-
-.. math::
- :label: myeq1
-
- {\partial u\over\partial t} = \nabla^2 u + f,
-
-
-
-
-.. math::
- :label: myeq2
-
- {\partial v\over\partial t} = \nabla\cdot(q(u)\nabla v) + g.
-
-
The support of LaTeX mathematics varies among the formats:
@@ -3281,70 +3318,21 @@
newcommands in the ``newcommands*.tex`` files *must* appear on a single
line (multi-line newcommands are too hard to parse with regular
expressions).
-
-*Example.* Suppose we have the following commands in
-``newcommand_replace.tex``:
-
-
-.. code-block:: text
-
-
- \newcommand{\beqa}{\begin{eqnarray}}
- \newcommand{\eeqa}{\end{eqnarray}}
- \newcommand{\ep}{\thinspace . }
- \newcommand{\uvec}{\vec u}
- \newcommand{\Q}{\pmb{Q}}
-
-
-and these in ``newcommands_keep.tex``:
-
-
-.. code-block:: text
-
-
- \newcommand{\x}{\pmb{x}}
- \newcommand{\normalvec}{\pmb{n}}
- \newcommand{\Ddt}[1]{\frac{D#1}{dt}}
- \newcommand{\half}{\frac{1}{2}}
-The LaTeX block
-
-.. code-block:: text
-
-
- \beqa
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{\uvec} &=& \Q \ep label{my:eq2}
- \eeqa
-
-will then be rendered to
-
-.. math::
-
- \pmb{x}\cdot\pmb{n} &= 0, \\
- \frac{D{\vec u}{dt}} &= \pmb{Q} {\thinspace . }
-
-
-in the current format.
-
Admonitions
-----------
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-``block``, ``warning``, ``notice``, ``hint``, ``question``, and
``summary``.
-The box is defined by begin and end tags such as ``!bhint`` and ``!ehint``.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the ``hint`` environment gives a
-box with some admonition icon, text and/or colored background.)
+``block``, ``warning``, ``notice``, ``question``, and ``summary``.
+The box is defined by begin and end tags such as ``!bnotice`` and
``!enotice``.
The title of the box is fully customizable.
Here are a few examples:
@@ -3357,9 +3345,9 @@
Here is a warning!
!ewarning
- !bhint
+ !bnotice Hint
This is a hint.
- !ehint
+ !enotice
!bblock This is a block.
A block has never any icon.
@@ -3383,8 +3371,9 @@
.. warning::
Here is a warning!
+
+.. admonition:: Hint
-.. hint::
This is a hint.
@@ -3686,6 +3675,7 @@
Emacs Doconce Formatter
-----------------------
+
The file `.doconce-mode.el
<https://doconce.googlecode.com/hg/misc/.doconce-mode.el>`_ in the Doconce
source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3787,8 +3777,10 @@
.. font sizes are compatible
+
+Not yet written...
-Text is missing... Just a very preliminary sketch of commands:
+Just a very preliminary sketch of commands:
.. code-block:: console
@@ -3810,6 +3802,17 @@
LaTeX Beamer Slides
-------------------
+Not yet written...
+
+Themes
+~~~~~~
+
+Four themes come with Doconce: ``X_Y``, where ``X`` is ``blue`` or ``red``
+(the main color of the slides) and ``Y`` is `plain
<http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf>`_
+for simple layout and
+`shadow
<http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf>`_
+for shadowed boxes and more visual structure in the slides.
+
Mako Programming
================
@@ -3820,6 +3823,16 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+.. warning::
+ Unfortunately, the combination of Mako and LaTeX mathematics may
+ lead to problems because Mako applies syntax like ``${var}`` to extract
+ variables or call functions, while LaTeX mathematics sometimes applies
+ the same syntax, e.g., ``${\cal O}(\Delta x^2)$`` which looks like a
+ Mako function call. This problem can give rise to strange error
+ messages from Mako, usually that a variable is not defined.
+
+
The Basics of Mako
------------------
@@ -4015,6 +4028,16 @@
General Problems
----------------
+Spellcheck reports a lot of mistakes related LaTeX math
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``doconce spellcheck`` command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant ``tmp_missing_*`` file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
Doconce aborts because of a syntax error that is not an error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4042,6 +4065,27 @@
* Strings with ``'T<%.1f'`` look as openings of Mako blocks (``<%``);
change
to ``'T < %.1f'`` to avoid this confusion.
+The Mako preprocessor claims a variable is undefined
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, :math:`{\cal O}(\Delta x^2)` is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use ``${`` anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is ``${}^+$`` type of indication of superscripts.
+A suggested rewrite is ``$\,{}^+$``.
+
+The error message will ask you to rerun ``doconce`` with
+``--mako_strict_undefined``, which will display the variable that
+is confusing Mako. However, do not continue to use
+``--mako_strict_undefined`` while you are debugging because this
+variable will then always be undefined in that mode.
+Use ``# #ifdef`` directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without ``--mako_strict_undefined``).
+
Something goes wrong in the preprocessing step
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4512,6 +4556,16 @@
Problems with HTML Output
-------------------------
+MathJax formulas are not properly rendered
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ * ``[`` and ``]`` brackets must sometimes be replaced by ``\lbrack`` and
``\rbrack``
+
How can I change the layout of the HTML page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================
--- /doc/demos/manual/manual.tex Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.tex Fri Jun 28 09:22:02 2013
@@ -37,10 +37,11 @@
\renewcommand\familydefault{phv}
% Hyperlinks in PDF:
+\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage[%
colorlinks=true,
- linkcolor=blue,
- urlcolor=blue,
+ linkcolor=linkcolor,
+ urlcolor=linkcolor,
citecolor=black,
filecolor=black,
%filecolor=blue,
@@ -75,10 +76,10 @@
% Admonition is an oval gray box
\newmdenv[
- backgroundcolor=gray!10, %% white with 10%% gray
+ backgroundcolor=gray!5, %% white with 5%% gray
skipabove=\topsep,
skipbelow=\topsep,
- outerlinewidth=0.5,
+ outerlinewidth=0,
leftmargin=0,
rightmargin=0,
roundcorner=5,
@@ -145,7 +146,7 @@
\begin{center}
-May 29, 2013
+Jun 28, 2013
\end{center}
\vspace{1cm}
@@ -705,7 +706,7 @@
\label{doconce2formats}
Transformation of a Doconce document \Verb!mydoc.do.txt! to various other
-formats applies the script \Verb!doconce format!:
+formats apply the script \Verb!doconce format!:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
Terminal> doconce format format mydoc.do.txt
\end{Verbatim}
@@ -892,6 +893,7 @@
code with MathJax
scripts so there is no support for mathematics in the discussion forum.
\end{graybox1admon}
+
\begin{graybox1admon}[Notice.]
Figure files must be uploaded to some web site and the filenames name must
be replaced by the relevant URL. This can be automatically edited:
@@ -908,6 +910,7 @@
# Paste mydoc2.html into a new blog page
\end{Verbatim}
\end{graybox1admon}
+
Blog posts at Google can also be published
\href{{http://support.google.com/blogger/bin/answer.py?hl=en&answer=41452}}{automatically
through email}.
A Python program can send the contents of the HTML file
to the blog's email address using the packages \Verb!smtplib! and
\Verb!email!.
@@ -1986,6 +1989,7 @@
becomes correct (sometimes a trial and error process - sticking to
very simple formatting usually avoids such problems).
\end{graybox1admon}
+
\paragraph{Links to Web Addresses.}
Web addresses with links are typeset as
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
@@ -2304,7 +2308,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-{\LaTeX} is the output format).
+{\LaTeX} is the output format). For paragraphs with \Verb!===! heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in \Verb!html! output such that search engines can make use of the
them.
\subsection{Bibliography}
@@ -2345,6 +2353,7 @@
curly braces. You may need to edit your \textsc{Bib}\negthinspace{\TeX}
files to meet this
demand.
\end{graybox1admon}
+
The utility \Verb!doconce fix_bibtex4publish file.bib! fixes several known
issues with \textsc{Bib}\negthinspace{\TeX} files such that Publish has a
better chance of
accepting the entries. Run this utility first, then run Publish,
@@ -2469,6 +2478,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes \Verb!|! can also be inserted to indicate
vertical rules in {\LaTeX} tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like
+
+\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+\end{Verbatim}
+
Note that not all formats offer alignment of heading or entries
in tables (\Verb!rst! and \Verb!sphinx! are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2480,6 +2502,33 @@
makes Doconce dump each table to CSV format in a file \Verb!table_X.csv!,
where \Verb!X! is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+
+Data in CSV format can be transformed to Doconce table format
+by the \Verb!doconce csv2table! utility:
+
+\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
+Terminal> doconce csv2table somefile.csv > table.do.txt
+\end{Verbatim}
+This is a quick way of writing tables. For example, we can
+write a text file \Verb!tmp.csv! with
+
+\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
+time, velocity, acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624
+\end{Verbatim}
+Running \Verb!doconce csv2table tmp.csv! creates the table
+
+\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
+|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
+\end{Verbatim}
\subsection{Exercises, Problems, Projects, and Examples}
@@ -2882,12 +2931,6 @@
\end{align}
!et
\end{Verbatim}
-Here is the result:
-
-\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, \label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. \label{myeq2}
-\end{align}
The support of {\LaTeX} mathematics varies among the formats:
@@ -2991,57 +3034,19 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-\paragraph{Example.}
-Suppose we have the following commands in
-\Verb!newcommand_replace.tex!:
-
-\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
-\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}
-\end{Verbatim}
-
-and these in \Verb!newcommands_keep.tex!:
-
-\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
-\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}
-\end{Verbatim}
-
-The {\LaTeX} block
-\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
-\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa
-\end{Verbatim}
-will then be rendered to
-\beqa
-\x\cdot\normalvec &=& 0, \label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep \label{my:eq2}
-\eeqa
-in the current format.
\subsection{Admonitions}
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-\Verb!block!, \Verb!warning!, \Verb!notice!, \Verb!hint!, \Verb!question!,
and \Verb!summary!.
-The box is defined by begin and end tags such as \Verb!!bhint! and
\Verb!!ehint!.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading \emph{Hint} (with number)
-appears, while outside exercises the \Verb!hint! environment gives a
-box with some admonition icon, text and/or colored background.)
+\Verb!block!, \Verb!warning!, \Verb!notice!, \Verb!question!, and
\Verb!summary!.
+The box is defined by begin and end tags such as \Verb!!bnotice! and
\Verb!!enotice!.
The title of the box is fully customizable.
Here are a few examples:
@@ -3051,9 +3056,9 @@
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -3077,17 +3082,21 @@
\begin{graybox1admon}[Warning.]
Here is a warning!
\end{graybox1admon}
+
\begin{graybox1admon}[Hint.]
This is a hint.
\end{graybox1admon}
+
\begin{graybox1admon}[This is a block.]
A block has never any icon.
\end{graybox1admon}
+
\begin{graybox1admon}[Going deeper.]
This is text meant to provide more details. The box has the
layout of the notice box, but a custom title, here "Going deeper".
\end{graybox1admon}
+
Finally some summary:
@@ -3095,6 +3104,7 @@
The main message is to utilize the admonition styles for
marking different parts of the text
\end{graybox1admon}
+
The layout of admonitions depend on the format.
In \Verb!rst! and \Verb!sphinx! one applies the native admonitions, but
in \Verb!sphinx! the \Verb!automake_sphinx.py! script manipulates the HTML
@@ -3365,6 +3375,7 @@
\subsection{Emacs Doconce Formatter}
\label{emacs:doconce}
+
The file
\href{{https://doconce.googlecode.com/hg/misc/.doconce-mode.el}}{.doconce-mode.el}
in the Doconce source distribution
gives a "Doconce Editing Mode" in Emacs.
@@ -3470,7 +3481,9 @@
% doconce-adjusted styles: easy to switch between styles since
% font sizes are compatible
-Text is missing... Just a very preliminary sketch of commands:
+Not yet written...
+
+Just a very preliminary sketch of commands:
\begin{Verbatim}[numbers=none,fontsize=\fontsize{9pt}{9pt},baselinestretch=0.85,xleftmargin=0mm]
Terminal> doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
@@ -3489,6 +3502,15 @@
\noindent
\subsection{{\LaTeX} Beamer Slides}
+
+Not yet written...
+
+\paragraph{Themes.}
+Four themes come with Doconce: \Verb!X_Y!, where \Verb!X! is \Verb!blue!
or \Verb!red!
+(the main color of the slides) and \Verb!Y! is
\href{{http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf}}{\nolinkurl{plain}}
+for simple layout and
+\href{{http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf}}{\nolinkurl{shadow}}
+for shadowed boxes and more visual structure in the slides.
\section{Mako Programming}
@@ -3498,6 +3520,16 @@
sufficient for if-else tests to steer which parts of the text that
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+
+
+\begin{graybox1admon}[Warning.]
+Unfortunately, the combination of Mako and {\LaTeX} mathematics may
+lead to problems because Mako applies syntax like \Verb!${var}! to extract
+variables or call functions, while {\LaTeX} mathematics sometimes applies
+the same syntax, e.g., \Verb!${\cal O}(\Delta x^2)$! which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+\end{graybox1admon}
\subsection{The Basics of Mako}
@@ -3673,6 +3705,14 @@
\subsection{General Problems}
+
+\paragraph{Spellcheck reports a lot of mistakes related {\LaTeX} math.}
+The \Verb!doconce spellcheck! command should ignore {\LaTeX} math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant \Verb!tmp_missing_*! file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
\paragraph{Doconce aborts because of a syntax error that is not an error.}
Doconce searches for typical syntax errors and usually aborts the
@@ -3698,6 +3738,25 @@
\end{itemize}
\noindent
+\paragraph{The Mako preprocessor claims a variable is undefined.}
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired {\LaTeX} syntax.
+For example, ${\cal O}(\Delta x^2)$ is valid {\LaTeX}, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use \Verb!${! anywhere in {\LaTeX}
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is \Verb!${}^+$! type of indication of superscripts.
+A suggested rewrite is \Verb!$\,{}^+$!.
+
+The error message will ask you to rerun \Verb!doconce! with
+\Verb!--mako_strict_undefined!, which will display the variable that
+is confusing Mako. However, do not continue to use
+\Verb!--mako_strict_undefined! while you are debugging because this
+variable will then always be undefined in that mode.
+Use \Verb!# #ifdef! directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without \Verb!--mako_strict_undefined!).
+
\paragraph{Something goes wrong in the preprocessing step.}
You can examine \Verb!tmp_preprocess__filename! and
\Verb!tmp_mako__filename!,
where \Verb!filename! is the complete name of the Doconce file, to see
@@ -3930,7 +3989,7 @@
When this package is included, \Verb!latex! or \Verb!pdflatex! runs the
\Verb!pygmentize! program and the \Verb!shell-escape! option is required.
-\paragraph{Why are the {\LaTeX} section headings smaller than normal?.}
+\paragraph{Why are the {\LaTeX} section headings smaller than normal?}
Doconce inserts a special command to make the headings
more compact:
@@ -3949,7 +4008,7 @@
by replacing \Verb![compact]! by \Verb![compact,small]! as parameter
specification
for \Verb!titlesec!.
-\paragraph{Can I have {\LaTeX} figures with shadows?.}
+\paragraph{Can I have {\LaTeX} figures with shadows?}
This is easy by including the \Verb!fancybox! and \Verb!graphicx! packages
and wrapping all \Verb!\includegraphics! in a shadow box:
@@ -3961,7 +4020,7 @@
'\\shadowbox{\g<1>}' mydoc.p.tex
\end{Verbatim}
-\paragraph{How can I use my fancy {\LaTeX} environments?.}
+\paragraph{How can I use my fancy {\LaTeX} environments?}
See Section~\ref{manual:theorem:envir} for how to make a custom
theorem environment also in Doconce, without using implementations
restricted to {\LaTeX}.
@@ -4049,7 +4108,18 @@
\subsection{Problems with HTML Output}
-\paragraph{How can I change the layout of the HTML page?.}
+\paragraph{MathJax formulas are not properly rendered.}
+Here are some common problems:
+
+\begin{itemize}
+ \item Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ \item \Verb![! and \Verb!]! brackets must sometimes be replaced by
\Verb!\lbrack! and \Verb!\rbrack!
+\end{itemize}
+
+\noindent
+\paragraph{How can I change the layout of the HTML page?}
The easiest way is to edit the HTML style or the HTML code directly.
However, those edits are overwritten the next time you compile the
Doconce document to HTML. The edits should therefore be automated
@@ -4086,7 +4156,7 @@
use the \Verb!sphinx! format and one its many themes.
-\paragraph{Why do figures look ugly when using HTML templates?.}
+\paragraph{Why do figures look ugly when using HTML templates?}
The HTML header that Doconce generates contain special styles for
figure captions and the horizontal rule above figures. When using
templates these styles are not defined, resulting in a rule that
=======================================
--- /doc/demos/manual/manual.txt Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.txt Fri Jun 28 09:22:02 2013
@@ -6,7 +6,7 @@
[1] Center for Biomedical Computing, Simula Research Laboratory
[2] Department of Informatics, University of Oslo
-Date: May 29, 2013
+Date: Jun 28, 2013
What Is Doconce?
================
@@ -565,7 +565,7 @@
=============================
Transformation of a Doconce document mydoc.do.txt to various other
-formats applies the script doconce format::
+formats apply the script doconce format::
Terminal> doconce format format mydoc.do.txt
@@ -2166,7 +2166,11 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).
+LaTeX is the output format). For paragraphs with === heading,
+the index keywords should be placed above the heading.
+
+The keywords in the index are automatically placed in a meta
+tag in html output such that search engines can make use of the them.
Bibliography
------------
@@ -2343,6 +2347,19 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes | can also be inserted to indicate
vertical rules in LaTeX tables (they are ignored for other formats).
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks like::
+
+
+ |--c--------c-----------c--------|
+ |time | velocity | acceleration |
+ |--l--------r-----------r--------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------|
+
+
Note that not all formats offer alignment of heading or entries
in tables (rst and sphinx are examples). Also note that
Doconce tables are very simple: neither entries nor
@@ -2355,6 +2372,33 @@
where X is the table number. This feature makes it easy to
load tables into spreadsheet programs for further analysis.
+Data in CSV format can be transformed to Doconce table format
+by the doconce csv2table utility::
+
+
+ Terminal> doconce csv2table somefile.csv > table.do.txt
+
+This is a quick way of writing tables. For example, we can
+write a text file tmp.csv with::
+
+
+ time, velocity, acceleration
+ 0.0, 1.4186, -5.01
+ 2.0, 1.376512, 11.919
+ 4.0, 1.1E+1, 14.717624
+
+Running doconce csv2table tmp.csv creates the table::
+
+
+ |------c--------------c--------------c-------|
+ | time | velocity | acceleration |
+ |------c--------------c--------------c-------|
+ | 0.0 | 1.4186 | -5.01 |
+ | 2.0 | 1.376512 | 11.919 |
+ | 4.0 | 1.1E+1 | 14.717624 |
+ |--------------------------------------------|
+
+
Exercises, Problems, Projects, and Examples
-------------------------------------------
@@ -2758,13 +2802,6 @@
\end{align}
!et
-Here is the result::
-
- \begin{align}
- {\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
- {\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
- \end{align}
-
The support of LaTeX mathematics varies among the formats:
@@ -2865,60 +2902,20 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
-*Example.* Suppose we have the following commands in
-newcommand_replace.tex::
-
-
- \newcommand{\beqa}{\begin{eqnarray}}
- \newcommand{\eeqa}{\end{eqnarray}}
- \newcommand{\ep}{\thinspace . }
- \newcommand{\uvec}{\vec u}
- \newcommand{\Q}{\pmb{Q}}
-
-
-and these in newcommands_keep.tex::
-
-
- \newcommand{\x}{\pmb{x}}
- \newcommand{\normalvec}{\pmb{n}}
- \newcommand{\Ddt}[1]{\frac{D#1}{dt}}
- \newcommand{\half}{\frac{1}{2}}
-
-
-The LaTeX block::
-
-
- \beqa
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{\uvec} &=& \Q \ep label{my:eq2}
- \eeqa
-
-will then be rendered to::
-
- \begin{eqnarray}
- \x\cdot\normalvec &=& 0, label{my:eq1}\\
- \Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
- \end{eqnarray}
-
-in the current format.
Admonitions
-----------
Doconce offers strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.
The following admonition environments are available:
-block, warning, notice, hint, question, and summary.
-The box is defined by begin and end tags such as !bhint and !ehint.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading *Hint* (with number)
-appears, while outside exercises the hint environment gives a
-box with some admonition icon, text and/or colored background.)
+block, warning, notice, question, and summary.
+The box is defined by begin and end tags such as !bnotice and !enotice.
The title of the box is fully customizable.
Here are a few examples::
@@ -2928,9 +2925,9 @@
Here is a warning!
!ewarning
- !bhint
+ !bnotice Hint
This is a hint.
- !ehint
+ !enotice
!bblock This is a block.
A block has never any icon.
@@ -3332,7 +3329,9 @@
------------
-Text is missing... Just a very preliminary sketch of commands::
+Not yet written...
+
+Just a very preliminary sketch of commands::
Terminal> doconce format html myslides \
@@ -3353,6 +3352,17 @@
LaTeX Beamer Slides
-------------------
+Not yet written...
+
+Themes
+~~~~~~
+
+Four themes come with Doconce: X_Y, where X is blue or red
+(the main color of the slides) and Y is plain
(http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf)
+for simple layout and
+shadow (http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf)
+for shadowed boxes and more visual structure in the slides.
+
Mako Programming
================
@@ -3363,6 +3373,14 @@
are to be compiled. For more demanding tasks, use Mako, which resembles
a real programming language.
+*Warning.*
+Unfortunately, the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like ${var} to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., ${\cal O}(\Delta x^2)$ which looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not defined.
+
The Basics of Mako
------------------
@@ -3545,6 +3563,16 @@
General Problems
----------------
+Spellcheck reports a lot of mistakes related LaTeX math
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The doconce spellcheck command should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant tmp_missing_* file and search for the math expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.
+
Doconce aborts because of a syntax error that is not an error
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3572,6 +3600,27 @@
* Strings with 'T<%.1f' look as openings of Mako blocks (<%); change
to 'T < %.1f' to avoid this confusion.
+The Mako preprocessor claims a variable is undefined
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Very often such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, {\cal O}(\Delta x^2) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use ${ anywhere in LaTeX mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is ${}^+$ type of indication of superscripts.
+A suggested rewrite is $\,{}^+$.
+
+The error message will ask you to rerun doconce with
+--mako_strict_undefined, which will display the variable that
+is confusing Mako. However, do not continue to use
+--mako_strict_undefined while you are debugging because this
+variable will then always be undefined in that mode.
+Use # #ifdef directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without --mako_strict_undefined).
+
Something goes wrong in the preprocessing step
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4009,6 +4058,16 @@
Problems with HTML Output
-------------------------
+MathJax formulas are not properly rendered
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are some common problems:
+
+ * Two equations cannot have identical label (this error often arises
+ from copying and pasting equations)
+
+ * [ and ] brackets must sometimes be replaced by \lbrack and \rbrack
+
How can I change the layout of the HTML page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================
--- /doc/demos/manual/manual.xml Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual.xml Fri Jun 28 09:22:02 2013
@@ -2,7 +2,7 @@
<!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils
Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">
<!-- Generated by Docutils 0.9 -->
<document source="manual.rst"><comment xml:space="preserve">Automatically
generated reST file from Doconce source
-(http://code.google.com/p/doconce/)</comment><section
ids="doconce-description" names="doconce\ description"><title>Doconce
Description</title><field_list><field><field_name>Author</field_name><field_body><paragraph>Hans
Petter
Langtangen</paragraph></field_body></field><field><field_name>Date</field_name><field_body><paragraph>May
29, 2013</paragraph></field_body></field></field_list><comment
xml:space="preserve">lines beginning with # are doconce comment
lines</comment><comment xml:space="preserve">(documents can also have mako
comment lines)</comment><target refid="what-is-doconce"/></section><section
ids="id1 what-is-doconce" names="what\ is\ doconce?
what:is:doconce"><title>What Is Doconce?</title><paragraph>Doconce is a
very simple and minimally tagged markup language that
+(http://code.google.com/p/doconce/)</comment><section
ids="doconce-description" names="doconce\ description"><title>Doconce
Description</title><field_list><field><field_name>Author</field_name><field_body><paragraph>Hans
Petter
Langtangen</paragraph></field_body></field><field><field_name>Date</field_name><field_body><paragraph>Jun
28, 2013</paragraph></field_body></field></field_list><comment
xml:space="preserve">lines beginning with # are doconce comment
lines</comment><comment xml:space="preserve">(documents can also have mako
comment lines)</comment><target refid="what-is-doconce"/></section><section
ids="id1 what-is-doconce" names="what\ is\ doconce?
what:is:doconce"><title>What Is Doconce?</title><paragraph>Doconce is a
very simple and minimally tagged markup language that
looks like ordinary ASCII text, much like what you would use in an
email, but the text can be transformed to numerous other formats,
including HTML, Sphinx, LaTeX, PDF, reStructuredText (reST), Markdown,
@@ -243,7 +243,7 @@
lot of formats, with a corresponding
<reference name="web demo"
refuri="https://doconce.googlecode.com/hg/doc/demos/tutorial/index.html">web
demo</reference><target ids="web-demo" names="web\ demo"
refuri="https://doconce.googlecode.com/hg/doc/demos/tutorial/index.html"/>
of the results.</paragraph><comment xml:space="preserve">Example on
including another Doconce file:</comment><target
refid="doconce2formats"/></section></section><section
ids="from-doconce-to-other-formats doconce2formats" names="from\ doconce\
to\ other\ formats doconce2formats"><title>From Doconce to Other
Formats</title><paragraph>Transformation of a Doconce document
<literal>mydoc.do.txt</literal> to various other
-formats applies the script <literal>doconce
format</literal>:</paragraph><literal_block
xml:space="preserve">Terminal> doconce format format
mydoc.do.txt</literal_block><paragraph>or just:</paragraph><literal_block
xml:space="preserve">Terminal> doconce format format
mydoc</literal_block><section ids="generating-a-makefile"
names="generating\ a\ makefile"><title>Generating a
makefile</title><paragraph>Producing HTML, Sphinx, and in particular LaTeX
documents from
+formats apply the script <literal>doconce
format</literal>:</paragraph><literal_block
xml:space="preserve">Terminal> doconce format format
mydoc.do.txt</literal_block><paragraph>or just:</paragraph><literal_block
xml:space="preserve">Terminal> doconce format format
mydoc</literal_block><section ids="generating-a-makefile"
names="generating\ a\ makefile"><title>Generating a
makefile</title><paragraph>Producing HTML, Sphinx, and in particular LaTeX
documents from
Doconce sources requires a few commands. Often you want to
produce several different formats. The relevant commands should
then be placed in a script that acts as a
"makefile".</paragraph><paragraph>The <literal>doconce
makefile</literal> can be used to automatically generate
@@ -991,7 +991,9 @@
index items related to a paragraph should be placed above the
paragraph one a separate line (and not in between the text or between
the paragraph heading and the text body, although this works fine if
-LaTeX is the output format).</paragraph></section><section
ids="bibliography-2" names="bibliography\ (2)"><title>Bibliography
(2)</title><paragraph>Doconce applies the software tool <reference
name="Publish"
refuri="https://bitbucket.org/logg/publish">Publish</reference><target
dupnames="publish" ids="id6" refuri="https://bitbucket.org/logg/publish"/>
to handle the bibliography in a
+LaTeX is the output format). For paragraphs with <literal>===</literal>
heading,
+the index keywords should be placed above the
heading.</paragraph><paragraph>The keywords in the index are automatically
placed in a meta
+tag in <literal>html</literal> output such that search engines can make
use of the them.</paragraph></section><section ids="bibliography-2"
names="bibliography\ (2)"><title>Bibliography
(2)</title><paragraph>Doconce applies the software tool <reference
name="Publish"
refuri="https://bitbucket.org/logg/publish">Publish</reference><target
dupnames="publish" ids="id6" refuri="https://bitbucket.org/logg/publish"/>
to handle the bibliography in a
document. With Publish it is easy to import BibTeX data and maintain a
database in a clean, self-explanatory textual format. From the Publish
format it is easy to go BibTeX and reST or straightforward Doconce
@@ -1069,7 +1071,14 @@
Similar character can be inserted in the line above the header to
algn the headings. Pipes <literal>|</literal> can also be inserted to
indicate
vertical rules in LaTeX tables (they are ignored for other formats).
-Note that not all formats offer alignment of heading or entries
+An example of centered headings (which is default anyway), first
+column left-adjusted and the others right-adjusted looks
like:</paragraph><literal_block xml:space="preserve">|
--c--------c-----------c--------|
+|time | velocity | acceleration |
+|--l--------r-----------r--------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------|</literal_block><paragraph>Note that not
all formats offer alignment of heading or entries
in tables (<literal>rst</literal> and <literal>sphinx</literal> are
examples). Also note that
Doconce tables are very simple: neither entries nor
headings can span several columns or rows. When that functionality
@@ -1077,7 +1086,18 @@
the format and insert format-specific code for
tables.</paragraph><paragraph>The command-line option
<literal>--tables2csv</literal> (to <literal>doconce format</literal>)
makes Doconce dump each table to CSV format in a file
<literal>table_X.csv</literal>,
where <literal>X</literal> is the table number. This feature makes it easy
to
-load tables into spreadsheet programs for further
analysis.</paragraph></section><section
ids="exercises-problems-projects-and-examples" names="exercises,\
problems,\ projects,\ and\ examples"><title>Exercises, Problems, Projects,
and Examples</title><paragraph>Doconce has special support for four types
of "exercises", named
+load tables into spreadsheet programs for further
analysis.</paragraph><paragraph>Data in CSV format can be transformed to
Doconce table format
+by the <literal>doconce csv2table</literal>
utility:</paragraph><literal_block xml:space="preserve">Terminal>
doconce csv2table somefile.csv >
table.do.txt</literal_block><paragraph>This is a quick way of writing
tables. For example, we can
+write a text file <literal>tmp.csv</literal>
with:</paragraph><literal_block xml:space="preserve">time, velocity,
acceleration
+0.0, 1.4186, -5.01
+2.0, 1.376512, 11.919
+4.0, 1.1E+1, 14.717624</literal_block><paragraph>Running <literal>doconce
csv2table tmp.csv</literal> creates the table:</paragraph><literal_block
xml:space="preserve">|------c--------------c--------------c-------|
+| time | velocity | acceleration |
+|------c--------------c--------------c-------|
+| 0.0 | 1.4186 | -5.01 |
+| 2.0 | 1.376512 | 11.919 |
+| 4.0 | 1.1E+1 | 14.717624 |
+|--------------------------------------------|
</literal_block></section><section
ids="exercises-problems-projects-and-examples" names="exercises,\
problems,\ projects,\ and\ examples"><title>Exercises, Problems, Projects,
and Examples</title><paragraph>Doconce has special support for four types
of "exercises", named
<emphasis>exercise</emphasis>, <emphasis>problem</emphasis>,
<emphasis>project</emphasis>, or <emphasis>example</emphasis>.
These are all typeset as special kind of
sections. Such sections start with a subsection
@@ -1355,10 +1375,7 @@
{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
\end{align}
-!et</literal_block><paragraph>Here is the
result:</paragraph><literal_block xml:space="preserve">\begin{align}
-{\partial u\over\partial t} &= \nabla^2 u + f, label{myeq1}\\
-{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g.
label{myeq2}
-\end{align}</literal_block><paragraph>The support of LaTeX mathematics
varies among the formats:</paragraph><block_quote><bullet_list
bullet="*"><list_item><paragraph>Output in LaTeX (<literal>latex</literal>
and <literal>pdflatex</literal> formats) has of course full
+!et</literal_block><paragraph>The support of LaTeX mathematics varies
among the formats:</paragraph><block_quote><bullet_list
bullet="*"><list_item><paragraph>Output in LaTeX (<literal>latex</literal>
and <literal>pdflatex</literal> formats) has of course full
support of all LaTeX mathematics, of
course.</paragraph></list_item><list_item><paragraph>The
<literal>html</literal> format supports single equations and multiple
equations
via the align environment, also with
labels.</paragraph></list_item><list_item><paragraph>Markdown
(<literal>pandoc</literal> format) allows single equations and inline
mathematics.</paragraph></list_item><list_item><paragraph>MediaWiki
(<literal>mwiki</literal> format) does not enable labels in equations and
hence
equations cannot be referred
to.</paragraph></list_item></bullet_list></block_quote><paragraph>The main
conclusion is that for
@@ -1414,39 +1431,21 @@
<literal>newcommands_replace.tex</literal> and expanded by Doconce. The
definitions of
newcommands in the <literal>newcommands*.tex</literal> files
<emphasis>must</emphasis> appear on a single
line (multi-line newcommands are too hard to parse with regular
-expressions).</paragraph><paragraph><emphasis>Example.</emphasis> Suppose
we have the following commands in
-<literal>newcommand_replace.tex</literal>:</paragraph><literal_block
xml:space="preserve">\newcommand{\beqa}{\begin{eqnarray}}
-\newcommand{\eeqa}{\end{eqnarray}}
-\newcommand{\ep}{\thinspace . }
-\newcommand{\uvec}{\vec u}
-\newcommand{\Q}{\pmb{Q}}</literal_block><paragraph>and these in
<literal>newcommands_keep.tex</literal>:</paragraph><literal_block
xml:space="preserve">\newcommand{\x}{\pmb{x}}
-\newcommand{\normalvec}{\pmb{n}}
-\newcommand{\Ddt}[1]{\frac{D#1}{dt}}
-\newcommand{\half}{\frac{1}{2}}</literal_block><paragraph>The LaTeX
block:</paragraph><literal_block xml:space="preserve">\beqa
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{\uvec} &=& \Q \ep label{my:eq2}
-\eeqa</literal_block><paragraph>will then be rendered
to:</paragraph><literal_block xml:space="preserve">\begin{eqnarray}
-\x\cdot\normalvec &=& 0, label{my:eq1}\\
-\Ddt{{\vec u}} &=& \pmb{Q} {\thinspace . } label{my:eq2}
-\end{eqnarray}</literal_block><paragraph>in the current
format.</paragraph></section><section ids="admonitions"
names="admonitions"><title>Admonitions</title><paragraph>Doconce offers
strong support for admonition environments, such
-as warning boxes, notification boxes, hint boxes, question boxes,
+expressions).</paragraph></section><section ids="admonitions"
names="admonitions"><title>Admonitions</title><paragraph>Doconce offers
strong support for admonition environments, such
+as warning boxes, notification boxes, question boxes,
and summary boxes. The boxes normally have an icon, a heading,
and may also have a background color. A special box, the block,
has never any icon and can be used when an icon would be disturbing
or misleading.</paragraph><paragraph>The following admonition environments
are available:
-<literal>block</literal>, <literal>warning</literal>,
<literal>notice</literal>, <literal>hint</literal>,
<literal>question</literal>, and <literal>summary</literal>.
-The box is defined by begin and end tags such as <literal>!bhint</literal>
and <literal>!ehint</literal>.
-(The hint box is typeset differently inside exercises compared to outside
-exericises: inside a plain paragraph heading <emphasis>Hint</emphasis>
(with number)
-appears, while outside exercises the <literal>hint</literal> environment
gives a
-box with some admonition icon, text and/or colored background.)
+<literal>block</literal>, <literal>warning</literal>,
<literal>notice</literal>, <literal>question</literal>, and
<literal>summary</literal>.
+The box is defined by begin and end tags such as
<literal>!bnotice</literal> and <literal>!enotice</literal>.
The title of the box is fully customizable.</paragraph><paragraph>Here are
a few examples:</paragraph><literal_block xml:space="preserve">!bwarning
Here is a warning!
!ewarning
-!bhint
+!bnotice Hint
This is a hint.
-!ehint
+!enotice
!bblock This is a block.
A block has never any icon.
@@ -1462,7 +1461,7 @@
!bsummary
The main message is to utilize the admonition styles for
marking different parts of the text
-!esummary</literal_block><paragraph>The above Doconce code is in the
present format rendered as</paragraph><warning><paragraph>Here is a
warning!</paragraph></warning><hint><paragraph>This is a
hint.</paragraph></hint><admonition
classes="admonition-this-is-a-block"><title>This is a
block</title><paragraph>A block has never any
icon.</paragraph></admonition><admonition
classes="admonition-going-deeper"><title>Going
deeper</title><paragraph>This is text meant to provide more details. The
box has the
+!esummary</literal_block><paragraph>The above Doconce code is in the
present format rendered as</paragraph><warning><paragraph>Here is a
warning!</paragraph></warning><admonition
classes="admonition-hint"><title>Hint</title><paragraph>This is a
hint.</paragraph></admonition><admonition
classes="admonition-this-is-a-block"><title>This is a
block</title><paragraph>A block has never any
icon.</paragraph></admonition><admonition
classes="admonition-going-deeper"><title>Going
deeper</title><paragraph>This is text meant to provide more details. The
box has the
layout of the notice box, but a custom title, here "Going
deeper".</paragraph></admonition><paragraph>Finally some
summary:</paragraph><admonition
classes="admonition-summary"><title>Summary</title><paragraph>The main
message is to utilize the admonition styles for
marking different parts of the text</paragraph></admonition><paragraph>The
layout of admonitions depend on the format.
In <literal>rst</literal> and <literal>sphinx</literal> one applies the
native admonitions, but
@@ -1641,17 +1640,26 @@
<literal>frac</literal> parameter for LaTeX Beamer) so they become
effective
on the
slide.</paragraph></list_item></bullet_list></block_quote><paragraph>Doconce
can generate two types of slides: HTML5+CSS3 type of
slides to be presented through a web browser, and classical
-LaTeX Beamer slides.</paragraph></section><section ids="html5-slides"
names="html5\ slides"><title>HTML5 Slides</title><comment
xml:space="preserve">doconce-adjusted styles: easy to switch between styles
since</comment><comment xml:space="preserve">font sizes are
compatible</comment><paragraph>Text is missing... Just a very preliminary
sketch of commands:</paragraph><literal_block
xml:space="preserve">Terminal> doconce format html myslides \
+LaTeX Beamer slides.</paragraph></section><section ids="html5-slides"
names="html5\ slides"><title>HTML5 Slides</title><comment
xml:space="preserve">doconce-adjusted styles: easy to switch between styles
since</comment><comment xml:space="preserve">font sizes are
compatible</comment><paragraph>Not yet
written...</paragraph><paragraph>Just a very preliminary sketch of
commands:</paragraph><literal_block xml:space="preserve">Terminal>
doconce format html myslides \
--pygments_html_style=native --keep_pygments_html_bg
Terminal> doconce slides_html myslides reveal \
--html_slide_theme=darkgray</literal_block><section
ids="potential-problems" names="potential\ problems"><title>Potential
Problems</title><block_quote><bullet_list
bullet="*"><list_item><paragraph>Some newer Firefox does not show rounded
corners of the
admonition boxes, e.g., notice and warning (tested on
Ubuntu)</paragraph></list_item><list_item><paragraph>Doconce performs some
adjustments of the spacing around
-equations. More edits (automate with <literal>doconce subst</literal>)
might be
needed.</paragraph></list_item></bullet_list></block_quote></section></section><section
ids="latex-beamer-slides" names="latex\ beamer\ slides"><title>LaTeX Beamer
Slides</title></section></section><section ids="mako-programming"
names="mako\ programming"><title>Mako Programming</title><system_message
backrefs="id15" level="2" line="3501" source="manual.rst"
type="WARNING"><paragraph>Duplicate explicit target name:
"mako".</paragraph></system_message><paragraph>The <reference
name="Mako" refuri="http://docs.makotemplates.org/">Mako</reference><target
dupnames="mako" ids="id15" refuri="http://docs.makotemplates.org/"/>
templating engine is used
+equations. More edits (automate with <literal>doconce subst</literal>)
might be
needed.</paragraph></list_item></bullet_list></block_quote></section></section><section
ids="latex-beamer-slides" names="latex\ beamer\ slides"><title>LaTeX Beamer
Slides</title><paragraph>Not yet written...</paragraph><section
ids="themes" names="themes"><title>Themes</title><paragraph>Four themes
come with Doconce: <literal>X_Y</literal>, where <literal>X</literal> is
<literal>blue</literal> or <literal>red</literal>
+(the main color of the slides) and <literal>Y</literal> is <reference
name="plain"
refuri="http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf">plain</reference><target
ids="plain" names="plain"
refuri="http://hplgit.github.io/teamods/doconce/demo/demo_red_plain.pdf"/>
+for simple layout and
+<reference name="shadow"
refuri="http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf">shadow</reference><target
ids="shadow" names="shadow"
refuri="http://hplgit.github.io/teamods/doconce/demo/demo_blue_shadow.pdf"/>
+for shadowed boxes and more visual structure in the
slides.</paragraph></section></section></section><section
ids="mako-programming" names="mako\ programming"><title>Mako
Programming</title><system_message backrefs="id15" level="2" line="3513"
source="manual.rst" type="WARNING"><paragraph>Duplicate explicit target
name: "mako".</paragraph></system_message><paragraph>The
<reference name="Mako"
refuri="http://docs.makotemplates.org/">Mako</reference><target
dupnames="mako" ids="id15" refuri="http://docs.makotemplates.org/"/>
templating engine is used
as preprocessor for Doconce documents, but the <reference
name="Preprocess"
refuri="http://code.google.com/p/preprocess">Preprocess</reference><target
dupnames="preprocess" ids="id16"
refuri="http://code.google.com/p/preprocess"/> is run prior to Mako and is
recommended for
including other files via <literal># #include
"filename"</literal>. Preprocess is also
sufficient for if-else tests to steer which parts of the text that
are to be compiled. For more demanding tasks, use Mako, which resembles
-a real programming language.</paragraph><section ids="the-basics-of-mako"
names="the\ basics\ of\ mako"><title>The Basics of
Mako</title><paragraph>Just a preliminary sketch of some Mako code (next
example is better!):</paragraph><literal_block xml:space="preserve">#
Define variables
+a real programming language.</paragraph><warning><paragraph>Unfortunately,
the combination of Mako and LaTeX mathematics may
+lead to problems because Mako applies syntax like
<literal>${var}</literal> to extract
+variables or call functions, while LaTeX mathematics sometimes applies
+the same syntax, e.g., <literal>${\cal O}(\Delta x^2)$</literal> which
looks like a
+Mako function call. This problem can give rise to strange error
+messages from Mako, usually that a variable is not
defined.</paragraph></warning><section ids="the-basics-of-mako" names="the\
basics\ of\ mako"><title>The Basics of Mako</title><paragraph>Just a
preliminary sketch of some Mako code (next example is
better!):</paragraph><literal_block xml:space="preserve"># Define variables
<%
mycounter = 1
mydict = {}
@@ -1779,7 +1787,12 @@
track down this syntax problem yourself. However, Doconce applies
regular expressions to a large extent for transforming text, and
regular expressions may sometimes fail. Therefore, there is a chance that
legal
-Doconce syntax is not treated properly.</paragraph></section><section
ids="general-problems" names="general\ problems"><title>General
Problems</title><section
ids="doconce-aborts-because-of-a-syntax-error-that-is-not-an-error"
names="doconce\ aborts\ because\ of\ a\ syntax\ error\ that\ is\ not\ an\
error"><title>Doconce aborts because of a syntax error that is not an
error</title><paragraph>Doconce searches for typical syntax errors and
usually aborts the
+Doconce syntax is not treated properly.</paragraph></section><section
ids="general-problems" names="general\ problems"><title>General
Problems</title><section
ids="spellcheck-reports-a-lot-of-mistakes-related-latex-math"
names="spellcheck\ reports\ a\ lot\ of\ mistakes\ related\ latex\
math"><title>Spellcheck reports a lot of mistakes related LaTeX
math</title><paragraph>The <literal>doconce spellcheck</literal> command
should ignore LaTeX math, but if
+the dollar signs for inline math are not correct (one missing, for
instance),
+a lot of math enters the text to be spellchecked. Invoke the
+relevant <literal>tmp_missing_*</literal> file and search for the math
expressions that
+are reported as misspellings. This will fortunately give you hint of
+what is wrong with the math typesetting.</paragraph></section><section
ids="doconce-aborts-because-of-a-syntax-error-that-is-not-an-error"
names="doconce\ aborts\ because\ of\ a\ syntax\ error\ that\ is\ not\ an\
error"><title>Doconce aborts because of a syntax error that is not an
error</title><paragraph>Doconce searches for typical syntax errors and
usually aborts the
execution if errors are found. However, it may happen,
especially in verbatim blocks, that Doconce reports syntax errors
that are not errors. To continue execution, simply add the
@@ -1789,7 +1802,21 @@
because it thinks these lines are Mako statements. Doconce detects
this problem and avoids running Mako. Examine the output from
Doconce: warnings are issued if Mako is not
run.</paragraph></section><section
ids="the-mako-preprocessor-is-fooled-by-doconce-text" names="the\ mako\
preprocessor\ is\ fooled\ by\ doconce\ text"><title>The Mako preprocessor
is fooled by Doconce text</title><paragraph>Here are possible problems for
Mako:</paragraph><block_quote><bullet_list
bullet="*"><list_item><paragraph>Strings with
<literal>'T<%.1f'</literal> look as openings of Mako blocks
(<literal><%</literal>); change
-to <literal>'T < %.1f'</literal> to avoid this
confusion.</paragraph></list_item></bullet_list></block_quote></section><section
ids="something-goes-wrong-in-the-preprocessing-step" names="something\
goes\ wrong\ in\ the\ preprocessing\ step"><title>Something goes wrong in
the preprocessing step</title><paragraph>You can examine
<literal>tmp_preprocess__filename</literal> and
<literal>tmp_mako__filename</literal>,
+to <literal>'T < %.1f'</literal> to avoid this
confusion.</paragraph></list_item></bullet_list></block_quote></section><section
ids="the-mako-preprocessor-claims-a-variable-is-undefined" names="the\
mako\ preprocessor\ claims\ a\ variable\ is\ undefined"><title>The Mako
preprocessor claims a variable is undefined</title><paragraph>Very often
such errors are related to typos when using Mako
+variables or functions, or correct yet undesired LaTeX syntax.
+For example, {cal O}(Delta x^2) is valid LaTeX, but
+the dollar sign and curly braces confuse Mako. Rewrite such
+mathematics. It is wise to not use <literal>${</literal> anywhere in LaTeX
mathematics.
+Create a newcommand if there are no other possible rewritings.
+A known common problem is <literal>${}^+$</literal> type of indication of
superscripts.
+A suggested rewrite is
<literal>$\,{}^+$</literal>.</paragraph><paragraph>The error message will
ask you to rerun <literal>doconce</literal> with
+<literal>--mako_strict_undefined</literal>, which will display the
variable that
+is confusing Mako. However, do not continue to use
+<literal>--mako_strict_undefined</literal> while you are debugging because
this
+variable will then always be undefined in that mode.
+Use <literal># #ifdef</literal> directives to comment out large portions of
+the text and apply a "bisection" procedure to locate where
+the Mako problem is (without
<literal>--mako_strict_undefined</literal>).</paragraph></section><section
ids="something-goes-wrong-in-the-preprocessing-step" names="something\
goes\ wrong\ in\ the\ preprocessing\ step"><title>Something goes wrong in
the preprocessing step</title><paragraph>You can examine
<literal>tmp_preprocess__filename</literal> and
<literal>tmp_mako__filename</literal>,
where <literal>filename</literal> is the complete name of the Doconce
file, to see
what the preprocessors actually to and if something is wrong in these
files before Doconce starts translating the text.
@@ -1935,7 +1962,8 @@
and because of the indentation in the original Doconce text, the gwiki
output looks somewhat ugly. The good thing is that this gwiki source
is seldom to be looked at - it is the Doconce source that one edits
-further.</paragraph></section></section><section
ids="problems-with-html-output" names="problems\ with\ html\
output"><title>Problems with HTML Output</title><section
ids="how-can-i-change-the-layout-of-the-html-page" names="how\ can\ i\
change\ the\ layout\ of\ the\ html\ page?"><title>How can I change the
layout of the HTML page?</title><paragraph>The easiest way is to edit the
HTML style or the HTML code directly.
+further.</paragraph></section></section><section
ids="problems-with-html-output" names="problems\ with\ html\
output"><title>Problems with HTML Output</title><section
ids="mathjax-formulas-are-not-properly-rendered" names="mathjax\ formulas\
are\ not\ properly\ rendered"><title>MathJax formulas are not properly
rendered</title><paragraph>Here are some common
problems:</paragraph><block_quote><bullet_list
bullet="*"><list_item><paragraph>Two equations cannot have identical label
(this error often arises
+from copying and pasting
equations)</paragraph></list_item><list_item><paragraph><literal>[</literal>
and <literal>]</literal> brackets must sometimes be replaced by
<literal>\lbrack</literal> and
<literal>\rbrack</literal></paragraph></list_item></bullet_list></block_quote></section><section
ids="how-can-i-change-the-layout-of-the-html-page" names="how\ can\ i\
change\ the\ layout\ of\ the\ html\ page?"><title>How can I change the
layout of the HTML page?</title><paragraph>The easiest way is to edit the
HTML style or the HTML code directly.
However, those edits are overwritten the next time you compile the
Doconce document to HTML. The edits should therefore be automated
using <literal>doconce subst</literal> (for regular expression editing) or
<literal>doconce replace</literal>
=======================================
--- /doc/demos/manual/manual_pdflatex.pdf Wed May 29 03:54:41 2013
+++ /doc/demos/manual/manual_pdflatex.pdf Fri Jun 28 09:22:02 2013
Binary file, no diff available.
=======================================
--- /doc/manual/make.sh Wed Apr 24 00:37:11 2013
+++ /doc/manual/make.sh Fri Jun 28 09:22:02 2013
@@ -31,6 +31,8 @@
# doconce html format:
$d2f html manual.do.txt --no_mako --no_pygments_html
if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi
+# Need a fix: remove newcommands (and math) when displayed on googlecode
+doconce subst -s '<!\-\- newcommands.*?\$\$.*?\$\$' '' manual.html
# Sphinx
$d2f sphinx manual.do.txt --no_mako
@@ -73,8 +75,10 @@
$d2f epytext manual.do.txt --no_mako
if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi
-$d2f st manual.do.txt --no_mako
-if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi
+#Problem with st
+#$d2f st manual.do.txt --no_mako
+#if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi
+
$d2f pandoc manual.do.txt --no_mako
if [ $? -ne 0 ]; then echo "make.sh: abort"; exit 1; fi
@@ -120,7 +124,7 @@
rm -rf demo
mkdir demo
-cp -r manual.do.txt manual.html figs manual.p.tex manual.tex manual.pdf
manual_pdflatex.pdf manual.rst manual.sphinx.rst manual.xml manual.rst.html
manual.rst.tex manual.rst.pdf manual.gwiki manual.cwiki manual.mwiki
manual.txt manual.epytext manual.st manual.md sphinx-rootdir/_build/html
demo
+cp -r manual.do.txt manual.html figs manual.p.tex manual.tex manual.pdf
manual_pdflatex.pdf manual.rst manual.sphinx.rst manual.xml manual.rst.html
manual.rst.tex manual.rst.pdf manual.gwiki manual.cwiki manual.mwiki
manual.txt manual.epytext manual.md sphinx-rootdir/_build/html demo
cd demo
cat > index.html <<EOF
@@ -167,7 +171,6 @@
<a href="manual.cwiki">Creole wiki</a>,
<a href="manual.mwiki">MediaWiki</a>,
<a href="manual.md">Markdown</a> (Pandoc extended version),
-<a href="manual.st">Structured Text</a>,
<a href="manual.epytext">Epytext</a>,
and maybe the most important format of all:
<a href="manual.txt">plain untagged ASCII text</a>.
=======================================
--- /doc/manual/manual.do.txt Mon Jun 24 11:00:38 2013
+++ /doc/manual/manual.do.txt Fri Jun 28 09:22:02 2013
@@ -1356,6 +1356,7 @@
\end{align}
|et
!ec
+# #ifdef EXTRA
Here is the result:
!bt
@@ -1364,6 +1365,7 @@
{\partial v\over\partial t} &= \nabla\cdot(q(u)\nabla v) + g. label{myeq2}
\end{align}
!et
+# #endif
The support of LaTeX mathematics varies among the formats:
@@ -1456,6 +1458,7 @@
line (multi-line newcommands are too hard to parse with regular
expressions).
+# #ifdef EXTRA
__Example.__ Suppose we have the following commands in
`newcommand_replace.tex`:
@@ -1480,6 +1483,7 @@
\eeqa
!et
in the current format.
+# #endif
===== Admonitions =====
=======================================
--- /lib/doconce/common.py Mon Jun 24 11:00:38 2013
+++ /lib/doconce/common.py Fri Jun 28 09:22:02 2013
@@ -5,7 +5,6 @@
here.
"""
import re, sys, urllib
-from misc import option
# Identifiers in the text used to identify code and math blocks
_CODE_BLOCK = '<<<!!CODE_BLOCK'
@@ -29,6 +28,12 @@
'--- end exercise ---'),
}
+def _abort():
+ if '--no_abort' in sys.argv:
+ print 'avoided abortion because of --no-abort'
+ else:
+ print 'Abort! (add --no_abort on the command line to avoid this
abortion)'
+ sys.exit(1)
def safe_join(lines, delimiter):
try:
@@ -38,10 +43,10 @@
if "'ascii' codec can't decode" in e and 'position' in e:
pos = int(e.split('position')[1].split(':'))
print filestr[pos-50:pos], '[problematic char]',
filestr[pos+1:pos+51]
- sys.exit(1)
+ _abort()
else:
print e
- sys.exit(1)
+ _abort()
def fix_backslashes(text):
"""
@@ -162,7 +167,7 @@
url = url.replace('%', '\\%').replace('#', '\\#')
return url
else:
- print 'BUG'; sys.exit(1)
+ print 'BUG'; _abort()
def align2equations(filestr, format):
"""Turn align environments into separate equation environments."""
@@ -259,7 +264,7 @@
plotfiles = sorted(glob.glob(filename))
if not plotfiles:
print 'No plotfiles on the form', filename
- sys.exit(1)
+ _abort()
basename = os.path.basename(plotfiles[0])
stem, ext = os.path.splitext(basename)
kwargs['casename'] = stem
@@ -328,12 +333,12 @@
print '\n\nTwo', pattern, 'after each other!\n'
for j in range(begin_ends[k-1][1], begin_ends[k][1]+1):
print lines[j]
- sys.exit(1)
+ _abort()
if begin_ends[-1][0].startswith('!b'):
print 'Missing %s after final %s' % \
(begin_ends[-1][0].replace('!b', '!e'),
begin_ends[-1][0])
- sys.exit(1)
+ _abort()
def remove_code_and_tex(filestr):
@@ -393,12 +398,12 @@
if len(code_blocks) != n:
print '*** BUG: found %d code block markers for %d initial code
blocks\nAbort!' % (n, len(code_blocks))
print 'Possible cause: !bc and !ec inside code blocks - replace by
|bc and |ec'
- sys.exit(1)
+ _abort()
n = filestr.count(_MATH_BLOCK)
if len(tex_blocks) != n:
print '*** BUG: found %d tex block markers for %d initial tex
blocks\nAbort!' % (n, len(tex_blocks))
print 'Possible cause: !bt and !et inside code blocks - replace by
|bt and |ec'
- sys.exit(1)
+ _abort()
lines = filestr.splitlines()
=======================================
--- /lib/doconce/cwiki.py Mon Mar 11 00:28:37 2013
+++ /lib/doconce/cwiki.py Fri Jun 28 09:22:02 2013
@@ -5,7 +5,7 @@
# Simple edit of gwiki.py
import re, os, commands, sys
-from common import default_movie, plain_exercise, insert_code_and_tex
+from common import default_movie, plain_exercise, insert_code_and_tex,
_abort
def cwiki_code(filestr, code_blocks, code_block_types,
tex_blocks, format):
@@ -37,7 +37,7 @@
if failure:
print '\n**** Warning: could not run', cmd
print 'Convert %s to PNG format manually' % filename
- sys.exit(1)
+ _abort()
filename = root + '.png'
caption = m.group('caption')
# keep label if it's there:
=======================================
--- /lib/doconce/doconce.py Mon Jun 24 11:00:38 2013
+++ /lib/doconce/doconce.py Fri Jun 28 09:22:02 2013
@@ -7,13 +7,6 @@
# citations is then lost)
OrderedDict = dict
-def _abort():
- if not option('no_abort'):
- print 'Abort! (add --no_abort on the command line to avoid this
abortion)'
- sys.exit(1)
- else:
- print 'avoided abortion because of --no-abort'
-
def debugpr(out):
"""Add the text in string `out` to the log file (name in _log
variable)."""
@@ -25,6 +18,7 @@
from common import *
+from common import _abort # needs explicit import because of leading _
from misc import option, which
import html, latex, pdflatex, rst, sphinx, st, epytext, plaintext, gwiki,
mwiki, cwiki, pandoc, ipynb
@@ -2570,7 +2564,7 @@
names = supported_format_names()
if format not in names:
print '%s is not among the supported formats:\n%s' % (format,
names)
- sys.exit(1)
+ _abort()
encoding = option('encoding=', default='')
=======================================
--- /lib/doconce/gwiki.py Mon Mar 11 00:28:37 2013
+++ /lib/doconce/gwiki.py Fri Jun 28 09:22:02 2013
@@ -6,7 +6,7 @@
import re, os, commands, sys
-from common import default_movie, plain_exercise, insert_code_and_tex
+from common import default_movie, plain_exercise, insert_code_and_tex,
_abort
def gwiki_code(filestr, code_blocks, code_block_types,
tex_blocks, format):
@@ -38,7 +38,7 @@
if failure:
print '\n**** Warning: could not run', cmd
print 'Convert %s to PNG format manually' % filename
- sys.exit(1)
+ _abort()
filename = root + '.png'
caption = m.group('caption')
# keep label if it's there:
=======================================
--- /lib/doconce/html.py Mon Jun 24 11:00:38 2013
+++ /lib/doconce/html.py Fri Jun 28 09:22:02 2013
@@ -1,7 +1,7 @@
import re, os, glob, sys, glob
from common import table_analysis, plain_exercise, insert_code_and_tex, \
indent_lines, python_online_tutor, bibliography, \
- cite_with_multiple_args2multiple_cites
+ cite_with_multiple_args2multiple_cites, _abort
from misc import option
global _file_collection_filename
@@ -251,7 +251,7 @@
legal_styles += ['no', 'none']
if pygm_style not in legal_styles:
print 'pygments style "%s" is not legal, must be among\n%s' %
(pygm_style, ', '.join(legal_styles))
- #sys.exit(1)
+ #_abort()
print 'using the default style...'
pygm_style = 'default'
if pygm_style in ['no', 'none']:
@@ -266,7 +266,7 @@
if pygm is None:
print '*** error: cannot use Python Online Tutorial
(pyproopt)'
print ' without pygmentized code'
- sys.exit(1)
+ _abort()
code_blocks[i] = python_online_tutor(code_blocks[i],
return_tp='iframe')
@@ -504,14 +504,14 @@
# edit template_vargrant.html to template_mystyle.html
--html_template=template_mystyle.html
"""
- sys.exit(1)
+ _abort()
if 'template_vagrant.html' in template \
and not option('html_style=') == 'vagrant':
print """
*** error: --html_template= with a template based on
template_vagrant.html requires --html_style=vagrant
"""
- sys.exit(1)
+ _abort()
if template:
title = ''
@@ -544,11 +544,11 @@
if m:
title = m.group(1).strip()
filestr = re.sub(pattern, '\n<h1>%s</h1>\n' % title,
filestr)
-
- # Now use the first heading as title
- m = re.search(r'<h\d>(.+?)<a name=', filestr)
- if m:
- title = m.group(1).strip()
+ else:
+ # Use the first ordinary heading as title
+ m = re.search(r'<h\d>(.+?)<a name=', filestr)
+ if m:
+ title = m.group(1).strip()
# Extract date
pattern = r'<center><h\d>(.+?)</h\d></center>\s*<!-- date -->'
@@ -580,7 +580,7 @@
f = open(template, 'r'); template = f.read(); f.close()
except IOError:
print '*** error: could not find template "%s"' % template
- print 'Abort!'; sys.exit(1)
+ _abort()
# Check that template does not have "main content" begin and
# end lines that may interfere with the automatically generated
@@ -591,7 +591,7 @@
print ' with markers that doconce inserts - remove these'
for line in m:
print line
- print 'Abort!'; sys.exit(1)
+ _abort()
# template can only have slots for title, date, main
template = latin2html(template) # code non-ascii chars
@@ -746,7 +746,7 @@
plotfiles = glob.glob(filename)
if not plotfiles:
print 'No plotfiles on the form', filename
- sys.exit(1)
+ _abort()
plotfiles.sort()
basename = os.path.basename(plotfiles[0])
stem, ext = os.path.splitext(basename)
@@ -997,8 +997,7 @@
print e
print '*** error: problems in %s' % pubfile
print ' with key', label
- print 'Abort!'
- sys.exit(1)
+ _abort()
filestr = re.sub(r'^BIBFILE:.+$', bibtext, filestr,
flags=re.MULTILINE)
@@ -1261,7 +1260,7 @@
if body_font_family == '?' or body_font_family == 'help' or \
heading_font_family == '?' or heading_font_family == 'help':
print ' '.join(google_fonts)
- sys.exit(1)
+ _abort()
link = "@import url(http://fonts.googleapis.com/css?family=%s);"
import_body_font = ''
if body_font_family is not None:
=======================================
--- /lib/doconce/latex.py Mon Jun 24 11:00:38 2013
+++ /lib/doconce/latex.py Fri Jun 28 09:22:02 2013
@@ -4,7 +4,7 @@
from common import plain_exercise, table_analysis, \
_CODE_BLOCK, _MATH_BLOCK, doconce_exercise_output, indent_lines, \
python_online_tutor, envir_delimiter_lines, safe_join, \
- insert_code_and_tex
+ insert_code_and_tex, _abort
from misc import option
additional_packages = '' # comma-sep. list of packages for \usepackage{}
@@ -92,7 +92,7 @@
if current_code_envir is None:
# There should have been checks for this in doconce.py
print '*** errror: mismatch between !bc and !ec, line', i
- sys.exit(1)
+ _abort()
lines[i] = '\\b' + current_code_envir
if lines[i].startswith('!ec'):
lines[i] = '\\e' + current_code_envir
@@ -208,12 +208,12 @@
except IOError, e:
print 'tried to download %s, but failure:' % filename, e
print '*** error: cannot treat latex figure on the net (no
connection or invalid URL)'
- sys.exit(1)
+ _abort()
file_content = f.read()
f.close()
if 'DOCTYPE html' in file_content:
print '*** error: could not download', filename
- sys.exit(1)
+ _abort()
f = open(basename, 'w')
f.write(file_content)
f.close()
@@ -376,7 +376,7 @@
print 'Table has column alignment specification: %s, but %d
columns' \
% (column_spec, ncolumns)
print 'Table with rows', table['rows']
- sys.exit(1)
+ _abort()
# we do not support | in headings alignments (could be fixed,
# by making column_spec not a string but a list so the
@@ -386,7 +386,7 @@
print 'Table has headings alignment specification: %s, '\
'but %d columns' % (heading_spec, ncolumns)
print 'Table with rows', table['rows']
- sys.exit(1)
+ _abort()
s = '\n' + r'\begin{quote}\begin{tabular}{%s}' % column_spec + '\n'
for i, row in enumerate(table['rows']):
@@ -944,6 +944,15 @@
# _admon, _admon2rgb[_admon]))
+def latex_subsubsection(m):
+ title = m.group('subst').strip()
+ if title[-1] in ('?', '!', '.', ':',):
+ pass
+ else:
+ title += '.'
+ return r'\paragraph{%s}' % title
+
+
def latex_inline_comment(m):
name = m.group('name')
comment = m.group('comment')
@@ -1022,7 +1031,7 @@
'section': r'\section{\g<subst>}',
'subsection': r'\subsection{\g<subst>}',
#'subsubsection': '\n' + r'\subsubsection{\g<subst>}' + '\n',
- 'subsubsection': r'\paragraph{\g<subst>.}',
+ 'subsubsection': latex_subsubsection,
'paragraph': r'\paragraph{\g<subst>}\n',
#'abstract': '\n\n' + r'\\begin{abstract}' + '\n' +
r'\g<text>' + '\n' + r'\end{abstract}' + '\n\n' + r'\g<rest>', # not
necessary with separate \n
#'abstract':
r'\n\n\\begin{abstract}\n\g<text>\n\end{abstract}\n\n\g<rest>',
@@ -1429,7 +1438,7 @@
backgroundcolor=gray!5, %% white with 5%% gray
skipabove=\topsep,
skipbelow=\topsep,
- outerlinewidth=0.5,
+ outerlinewidth=0,
leftmargin=0,
rightmargin=0,
roundcorner=5,
=======================================
--- /lib/doconce/misc.py Mon Jun 24 11:00:38 2013
+++ /lib/doconce/misc.py Fri Jun 28 09:22:02 2013
@@ -1,4 +1,5 @@
import os, sys, shutil, re, glob, sets, time, commands
+from common import _abort
_registered_command_line_options = [
('--help',
@@ -126,11 +127,22 @@
option_name = '--' + name
if not option_name in _legal_command_line_options:
print 'test for illegal option:', option_name
- print 'Abort!'
- sys.exit(1)
+ _abort()
value = default
+ # Check if a command-line option has dash instead of underscore,
+ # which is a common mistake
+ for arg in sys.argv[1:]:
+ if arg.startswith('--'):
+ if '=' in arg:
+ arg = arg.split('=')[0] + '='
+ if arg not in _legal_command_line_options and \
+ ('--' + arg[2:].replace('-', '_')) in
_legal_command_line_options:
+ print 'found option %s, should be %s' % \
+ (arg, '--' + arg[2:].replace('-', '_'))
+ _abort()
+
# Check first if name is in configuration file (doconce_config)
name_dash2underscore = name.replace('-', '_')
if hasattr(doconce_config, name_dash2underscore):
@@ -171,8 +183,7 @@
if failure:
print 'could not run', cmd, failure_info
if abort_on_failure:
- print 'Abort!'
- sys.exit(1)
+ _abort()
def recommended_html_styles_and_pygments_styles():
"""
@@ -223,7 +234,7 @@
filename = sys.argv[1]
except IndexError:
print 'Usage: doconce remove_inline_comments myfile.do.txt'
- sys.exit(1)
+ _abort()
shutil.copy(filename, filename + '.old~~')
f = open(filename, 'r')
@@ -268,7 +279,7 @@
except IndexError:
print 'Usage: %s wikifile URL-stem' % sys.argv[0]
print 'Ex: %s somefile.gwiki
http://code.google.com/p/myproject/trunk/doc/somedir' % sys.argv[0]
- sys.exit(1)
+ _abort()
# first grep out all filenames with local path:
shutil.copy(gwikifile, gwikifile + '.old~~')
@@ -492,7 +503,7 @@
if os.path.splitext(filename)[1] != '.rst':
print 'Wrong filename extension in "%s" - must be a .rst file' \
% filename
- sys.exit(1)
+ _abort()
f = open(filename, 'r')
text = f.read()
@@ -1002,7 +1013,7 @@
filename
except:
print 'no specification of the .p.tex file'
- sys.exit(1)
+ _abort()
# Find which environments that will be defined and which
# latex packages that must be included.
@@ -1055,8 +1066,8 @@
if not os.path.isfile(filename + '.p.tex'):
- print 'No file %s' % (filename + '.p.tex')
- sys.exit(1)
+ print 'no file %s' % (filename + '.p.tex')
+ _abort()
output_filename = filename + '.tex'
cmd = 'preprocess %s %s > %s' % \
@@ -1114,7 +1125,7 @@
print 'You have requested the minted latex style, but this'
print 'requires the pygments package to be installed. On
Debian/Ubuntu: run'
print 'Terminal> sudo apt-get install python-pygments'
- sys.exit(1)
+ _abort()
# --- Treat the \code{} commands ---
@@ -1167,7 +1178,7 @@
filename = sys.argv[-1]
if not sys.argv[1].startswith('--from'):
print 'missing --from fromtext or --from_ fromtext option on the
command line'
- sys.exit(1)
+ _abort()
from_included = sys.argv[1] == '--from'
from_text = sys.argv[2]
@@ -1425,8 +1436,8 @@
cmd = 'iconv -f %s -t %s %s > %s' % \
(from_enc, to_enc, backupfile, filename)
else:
- print 'Changing encoding is not implemented on Windows machines'
- sys.exit(1)
+ print 'changing encoding is not implemented on Windows machines'
+ _abort()
os.rename(filename, backupfile)
system(cmd)
@@ -1668,8 +1679,8 @@
if not filename.endswith('.html'):
filename += '.html'
if not os.path.isfile(filename):
- print 'doconce file in html format, %s, does not exist - abort' %
filename
- sys.exit(1)
+ print 'doconce file in html format, %s, does not exist' % filename
+ _abort()
basename = os.path.basename(filename)
filestem = os.path.splitext(basename)[0]
@@ -1781,8 +1792,7 @@
print 'no width',
else:
print '%g' % width,
- print '\nAbort!'
- sys.exit(1)
+ _abort()
else:
width = 1./len(row)
for s, c in enumerate(row):
@@ -3124,7 +3134,7 @@
# the slide type is legal (before calling this function)
print '*** error: slide type "%s" is not known - abort' % slide_tp
print 'known slide
types:', ', '.join(list(all_combinations.keys()))
- sys.exit(1)
+ _abort()
# We need the subdir with reveal.js, deck.js, or similar to show
# the HTML slides so add the subdir to the registered file collection
@@ -3138,7 +3148,7 @@
print '*** error: %s theme "%s" is not known - abort' % \
(slide_tp, theme)
print 'known
themes:', ', '.join(list(all_combinations[slide_tp].keys()))
- sys.exit(1)
+ _abort()
m = re.search(r'<title>(.*?)</title>', ''.join(parts[0]))
if m:
@@ -3354,7 +3364,7 @@
filename += '.tex'
if not os.path.isfile(filename):
print 'doconce file in latex format, %s, does not exist - abort' %
filename
- sys.exit(1)
+ _abort()
basename = os.path.basename(filename)
filestem = os.path.splitext(basename)[0]
@@ -3754,7 +3764,7 @@
else:
print 'Syntax error in line'
print line
- sys.exit(1)
+ _abort()
print label
labels.append(label)
@@ -4217,8 +4227,8 @@
try:
f = open(filename, 'r')
except IOError:
- print '\nThe file %s does not exist!' % filename
- sys.exit(1)
+ print '\nfile %s does not exist!' % filename
+ _abort()
verbose = 1 if option('debug') else 0
@@ -5426,8 +5436,8 @@
from pygments.styles import get_all_styles
except ImportError:
pygm = None
- print 'pygments is not installed...abort'
- sys.exit(1)
+ print 'pygments is not installed'
+ _abort()
class DoconceLexer(RegexLexer):
"""
@@ -5840,8 +5850,8 @@
bibfiles = sys.argv[1:]
for bibfile in bibfiles:
if not bibfile.endswith('.bib'):
- print bibfile, 'is not a BibTeX file - abort'
- sys.exit(1)
+ print bibfile, 'is not a BibTeX file'
+ _abort()
shutil.copy(bibfile, bibfile + '.old~~')
f = open(bibfile, 'r')
lines = f.readlines()
@@ -5909,8 +5919,7 @@
print '*** error: broken line'
print lines[i]
print 'Glue with previous line!'
- print 'Abort!'
- sys.exit(1)
+ _abort()
f = open(bibfile, 'w')
f.writelines(lines)
@@ -6047,10 +6056,10 @@
if not os.path.isfile(fromfile):
print fromfile, 'does not exist'
- sys.exit(1)
+ _abort()
if not os.path.isfile(tofile):
print tofile, 'does not exist'
- sys.exit(1)
+ _abort()
fromdate = time.ctime(os.stat(fromfile).st_mtime)
todate = time.ctime(os.stat(tofile).st_mtime)
@@ -6159,7 +6168,7 @@
print 'diff in %s.pdf' % diff_file
else:
print program, 'not supported'
- sys.exit(1)
+ _abort()
def _usage_diffgit():
#print 'Usage: doconce gitdiff diffprog file1 file2 file3'
=======================================
--- /lib/doconce/mwiki.py Mon Jun 3 07:41:20 2013
+++ /lib/doconce/mwiki.py Fri Jun 28 09:22:02 2013
@@ -143,9 +143,9 @@
cmd = 'convert %s png:%s' % (filename, root+'.png')
failure, output = commands.getstatusoutput(cmd)
if failure:
- print '\n**** warning: could not run\n', cmd
- print 'Convert %s to PNG format manually' % filename
- sys.exit(1)
+ print '\n**** warning: could not run ', cmd
+ print ' convert %s to PNG format manually' % filename
+ _abort()
filename = root + '.png'
caption = m.group('caption').strip()
=======================================
--- /lib/doconce/plaintext.py Mon Mar 11 00:28:37 2013
+++ /lib/doconce/plaintext.py Fri Jun 28 09:22:02 2013
@@ -59,8 +59,8 @@
try:
bibdict = eval(bibstr)
except:
- print 'Error in Python dictionary for bibliography in', pyfile
- sys.exit(1)
+ print '*** error: in Python dictionary for bibliography in', pyfile
+ _abort()
text = '\n\n======= Bibliography =======\n\n'
for label in citations:
# remove newlines in reference data:
=======================================
--- /lib/doconce/rst.py Tue Jun 11 01:50:39 2013
+++ /lib/doconce/rst.py Fri Jun 28 09:22:02 2013
@@ -125,8 +125,7 @@
Still %s left after handling of code and tex blocks. Problem is probably
that %s is not preceded by text which can be extended with :: (required).
""" % (pattern, pattern)
- print 'Abort!'
- sys.exit(1)
+ _abort()
# Final fixes
Reply all
Reply to author
Forward
0 new messages